Leonardo API - Complete Developer Guide

1) What the Leonardo API is

Leonardo is a creative generation platform with a visual-first web app and a Production API. The core developer workflow is "design visually → export code": teams iterate in the web UI (prompt, style, aspect ratio, upscales, canvas edits), then export the same configuration into code via the in-app "Get API Code" feature and run it at scale through the API.

2) Quickstart: API key to first generation

The fastest path: (1) create an API key in the Leonardo web app under API Access, (2) call a generation endpoint with your prompt and settings, (3) retrieve the result by polling or via webhook callback. Name keys by environment (e.g. myapp-dev, myapp-prod) so you can rotate safely.

curl -X POST "https://cloud.leonardo.ai/api/rest/v1/generations" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_LEONARDO_API_KEY" \
  -d '{
    "prompt": "A clean product hero shot of a smart watch on a white desk, soft natural light",
    "num_images": 4
  }'

3) Authentication and key safety

The Production API uses a standard Bearer token: set Authorization: Bearer <YOUR_API_KEY> on requests against the cloud.leonardo.ai/api/rest/v1 base path.

• Never call the API from browsers: a key exposed in client-side JavaScript can be extracted and used to spend your credits. Route all requests through your backend, where you can enforce auth, quotas, and guardrails.
• Separate keys per environment: at minimum dev and prod, so a leak or bug in one can be revoked without impacting the other.
• Store keys in a secrets manager (or encrypted env vars), never in source control, and redact Authorization headers from logs and error tracking.
• Validate requests in your backend so users can't request unlimited images or extreme resolutions, and add per-user quotas plus abuse protection on public endpoints.

4) Core endpoints: generations, retrieval, and lists

The API is built around the generation - a job that produces one or more outputs. The workflow is always: create a generation → wait → retrieve results and metadata.

// Poll generation until complete (conceptual)
createGeneration() -> { generationId }

repeat every 2-5 seconds with backoff:
  gen = GET /generations/{generationId}
  if gen.status in ("COMPLETE", "FAILED"): break

if COMPLETE: store image URLs + metadata
else: log error + show message

5) Uploads with presigned URLs

Many workflows start from an existing image: image-to-image, inpainting, upscaling, canvas editing, motion from an upload, or training datasets. Rather than posting raw bytes to Leonardo, upload endpoints return presigned S3 upload details: call POST /init-image, receive a temporary presigned URL and form fields, upload the file directly to S3, then use the returned image ID in generation requests.

curl -X POST "https://cloud.leonardo.ai/api/rest/v1/init-image" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_LEONARDO_API_KEY" \
  -d '{ "extension": "png" }'

6) Realtime Canvas (LCM): fast generation, refine, inpaint, upscale

Realtime Canvas is built around LCM (Latent Consistency Models) for sub-second, interactive iteration. If an image takes 20–40 seconds, users abandon - realtime workflows keep the UI alive with a quick preview, then offer a refine/upscale path for final quality.

• Create LCM generation: produce an initial image quickly.
• Instant refine: improve quality or steer details without starting over.
• LCM inpainting: edit regions while keeping the rest consistent.
• Alchemy Upscale: upscale and enhance details for the final asset.

7) Video generation: text-to-video and motion from images

The API includes text-to-video endpoints and recipes for generating motion from uploaded images - "turn a product still into a subtle motion clip," "animate a scene from text," or "create short promo clips for ads." In 2026 this spans first-party Motion 1.0 / 2.0 / 2.0 Fast plus hosted third-party video models for premium workloads.

curl -X POST "https://cloud.leonardo.ai/api/rest/v1/generations-text-to-video" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_LEONARDO_API_KEY" \
  -d '{
    "prompt": "A smooth camera pan across a minimalist workspace, soft daylight, cinematic",
    "duration": 4
  }'

• Async like images: submit prompt + settings, wait for completion, receive a video URL plus metadata. Always implement timeouts, polling, and webhooks for longer jobs.
• Motion from an upload: upload an init image via presigned URL → get an image ID → reference that ID in the motion/video request.
• Budget carefully: video is far more expensive than images - a single short Motion render can consume a token volume comparable to hundreds of standard images.

8) Models: first-party, third-party shelf, and custom

You can list platform models via the API and pass a model ID in generation requests, or train custom models on your own datasets for brand-consistent style. The 2026 model landscape looks like this:

• Fast experimentation: start with platform models, validate product-market fit first.
• Consistent brand style: plan a dataset + custom model training workflow (create dataset → upload images via presigned URLs → train → generate with the returned model ID).
• Interactive UX: use Realtime Canvas/LCM for previews, then refine/upscale.
• Dataset quality: consistency beats quantity; cover variation deliberately; avoid mixing unrelated concepts; keep a fixed prompt suite to evaluate model versions objectively; version everything.

9) Webhook callbacks: results without polling

Polling is simple, but webhooks win at scale: configure a webhook callback URL when creating an API key so generation results are delivered to your server. This cuts latency and polling traffic, and lets long jobs run without a waiting client. An optional webhook callback API key is sent to your endpoint as authorization: Bearer <yourWebhookCallbackApiKey> - validate it.

// Conceptual webhook callback handler
raw = readRawBody(req)
auth = req.headers["authorization"]

if auth != "Bearer YOUR_WEBHOOK_CALLBACK_API_KEY": return 401

payload = JSON.parse(raw)

// Dedupe by generationId (and/or event id)
if seen(payload.generationId): return 200

enqueue("leonardo_generation_completed", payload)
markSeen(payload.generationId)
return 200

• Fast acknowledge: respond 2xx quickly; push heavy processing into a queue/job system.
• Idempotency: webhooks can arrive more than once - dedupe by generation ID + event type, and use upserts downstream.
• Keep polling as a fallback: mature systems use webhooks for real-time plus a reconciliation job (e.g. nightly) that polls for any generations that never received a callback.

10) Limits, concurrency, and queue

Design for three separate capacity constraints, all documented explicitly by Leonardo: rate limits (requests per window), concurrency (simultaneous jobs - the API supports up to 10 concurrent generations), and the queue (what happens when concurrency is maxed and jobs wait).

• Backoff on rate-limit errors: exponential with jitter - never hammer the API.
• Cap concurrency in your own worker pool rather than letting the platform queue grow unbounded.
• Batch thoughtfully: spread requests across time; don't spike thousands at once.
• Use webhooks to avoid tight polling loops that burn rate-limit budget.
• Show user states: "Generating", "Queued", "Finalizing", "Failed" - with helpful actions.

11) Pricing: pay-as-you-go API + app plans

The developer API is pure usage-based: start with a $5 credit, pay per token, enable auto top-ups, and run up to 10 concurrent generations. The self-serve app runs on seat-plus-bundled-token plans. Because every generation is metered in one shared token currency, cost planning matters - heavier models and video consume far more per output.

• Cost drivers you control: images per request, resolution, upscale usage (only upscale the winner), retries (dedupe aggressively), and prompt-experimentation loops.
• Cost visibility patterns: show estimated credit cost before generating (a Pricing Calculator endpoint exists for pre-flight estimates), offer draft-vs-final toggles, per-user budgets, and log cost metadata per generation.
• Reduce cost without hurting quality: two-stage LCM preview → refine/upscale on selection; cache results for repeated template prompts; hash request parameters to return the last successful output on repeated clicks.

Prices and token allowances change often and vary with annual billing (~20% off). Confirm current numbers on leonardo.ai/pricing and the official pricing FAQ before building billing logic.

12) Official SDKs: TypeScript and Python

Leonardo provides official TypeScript and Python SDKs that wrap the REST endpoints, standardize auth and errors, and keep request shapes aligned with the reference as it evolves.

• Initialize the client with an API key from your secrets manager.
• Wrap calls with your own retry/backoff policy for transient errors.
• Normalize responses into your internal schema (generationId, status, asset URLs, metadata).
• Centralize logging and error handling so secrets are redacted in one place.

13) Production architecture that doesn't break

The hard part isn't calling an endpoint - it's delivering a reliable product experience: controlling concurrency, handling queue states, managing costs, and supporting retries and user expectations.

// Prevent duplicate generations (a major hidden cost driver)
hash = sha256(userId + prompt + modelId + width + height + numImages + seed + options)

if existingGenerationByHash(hash) and status not FAILED:
  return existingGeneration
else:
  create new generation and store hash

• Guardrails: parameter caps (max images, resolution, video duration), per-user quotas, prompt content policy, queue-aware UX, and backoff policies.
• Batch workloads (e.g. 10,000 images): worker pool with strict concurrency limits and checkpointing; store generation IDs as you create them; process completion via webhooks; adaptive polling with jitter as a fallback; download outputs to your own storage as they complete; retry failures with capped attempts.
• Creator-friendly UI ingredients: prompt templates, "improve prompt" button, preset styles, aspect-ratio controls, LCM draft mode, refine/upscale pipeline, inpainting edit step, side-by-side variant comparison, and parameter history for reproducibility.

14) FAQ: Leonardo API

Official Leonardo docs

For accurate, current parameter lists, request/response schemas, and feature availability, always confirm against the official documentation: