1) What the Leonardo API is

Leonardo is a creative generation platform with a visual-first web app and a Production API. Many teams iterate in the web UI (prompt, style, aspect ratio, upscales, canvas edits), then export the same settings into code and use them at scale. That “design visually → export code” workflow is explicitly supported by Leonardo’s developer experience and docs.

What you can build with Leonardo API

2) Quickstart: from API key to your first generation

The fastest path to a working integration is: (1) create an API key in the Leonardo web app (API Access), (2) call a generation endpoint with your prompt and settings, (3) retrieve the result by polling or receiving a webhook callback.

https://cloud.leonardo.ai/api/rest/v1

Step C: Create an image generation (text-to-image)

The exact parameters depend on your chosen model and feature set, but the basic idea is consistent: send a prompt plus a small set of controls (size, number of images, optional negative prompt, and a model ID if needed). The endpoint shown in the official reference for “Create a Generation of Images” is: POST /generations.

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

Leonardo’s Production API uses a standard Bearer token pattern: set Authorization: Bearer <YOUR_API_KEY> on requests. Most endpoints in the reference show “Credentials: Bearer” and a base path like https://cloud.leonardo.ai/api/rest/v1/....

Recommended security baseline

• Store keys in a secrets manager (or encrypted env vars) rather than source control.
• Redact Authorization headers from logs and error tracking.
• Apply request validation in your backend so users can’t request unlimited images or extreme resolutions.
• Implement per-user quotas if your product exposes generation to end users.
• Add abuse protection (rate limiting, bot checks) to any public endpoints that trigger generation.

4) Core endpoints: generations, retrieval, and user lists

Leonardo’s Production API is built around the concept of a generation. A generation is a job that produces one or more outputs (images or video). The typical workflow is: create a generation → wait → retrieve results and metadata.

Polling workflow example (recommended baseline)

Even if you plan to use webhook callbacks, implement polling as a fallback. Polling gives you a simple “source of truth” path when your webhook endpoint is down or when you need to re-check status.

// Pseudo-code: 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: init images, masks, and dataset images

Many Leonardo workflows start from an existing image: image-to-image generation, inpainting (edit a region), upscaling, canvas editing, motion from an uploaded image, or custom model training datasets. Instead of uploading raw bytes directly to Leonardo’s API, the platform commonly returns presigned S3 upload details.

Upload an init image (for image-to-image and edits)

The official reference includes an “Upload init image” endpoint at: POST /init-image. It returns presigned details for uploading an init image to S3.

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"
  }'

After you receive presigned details, you upload the file to the provided S3 URL. Then you use the returned image ID as init_image_id in a generation request.

Canvas editor: upload init + mask

For inpainting and canvas edits, you often need both an init image and a mask. Leonardo provides a canvas upload endpoint (e.g., POST /canvas-init-image) that returns presigned details to upload both files.

Dataset uploads (for training custom models or elements)

Custom model training typically uses dataset creation and dataset image upload endpoints. Dataset image upload endpoints return presigned URLs and may expire quickly, so your client should upload immediately.

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

Leonardo includes a Realtime Canvas capability built around faster generation workflows, referenced in the API docs and recipes as LCM (Latent Consistency Models). The purpose is to make “creative iteration” feel interactive: generate quickly, refine, then inpaint or upscale.

Typical Realtime Canvas operations

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

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

Leonardo’s API reference includes endpoints for creating video generation from a text prompt (text-to-video) and documentation recipes for generating motion using uploaded images. This enables workflows such as: “turn a product still into a subtle motion clip,” “animate a scene from text,” or “create short promo clips for ads.”

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
  }'

Motion from an uploaded image

If you want to animate a user’s image (for example, a product photo or hero illustration), the recommended pattern is: upload an init image via a presigned URL endpoint → receive an image ID → reference that ID in the motion/video request.

8) Models: platform models and custom models

Leonardo supports using platform models (built-in, hosted) and custom models trained from your own datasets. In API docs, you can list platform models and use a model ID in generation requests. Once a custom model is trained, you can generate images by specifying that model ID as well.

How to choose a model (practical guidance)

• If you need fast experimentation: start with platform models, validate product-market fit.
• If you need consistent brand style: plan a dataset + custom model training workflow.
• If you need interactive UX: use Realtime Canvas/LCM for previews, then refine/upscale.
• If you need “templated” results: use prompt templates, negative prompts, and constrained settings.

9) Datasets + training: how custom models become production features

Training custom models is the “step up” from a basic API integration to a real creative platform. It adds operational complexity—dataset preparation, uploads, training time, monitoring—but it can unlock an experience that feels proprietary: “your brand, your style, consistently.”

What a training pipeline typically includes

Dataset best practices (what actually improves results)

• Consistency beats quantity: a smaller set of high-quality, consistent images can outperform a noisy dataset.
• Cover variation deliberately: include the variations you want the model to learn (angles, lighting, backgrounds).
• Avoid mixed concepts: don’t blend unrelated subjects into one dataset unless you want the model to merge them.
• Use a prompt suite: keep a short list of test prompts so you can evaluate changes objectively.
• Version everything: dataset version, training settings, resulting model ID, and evaluation notes.

10) Webhook callbacks: receiving results without polling

Polling is simple, but webhook callbacks are usually better at scale. Leonardo supports a webhook callback feature you can configure when creating an API key (or within settings) so that generation results can be delivered to your server. This reduces latency, reduces polling traffic, and lets you run long generation jobs without keeping a client waiting.

Webhook callback design (recommended)

// Pseudo-code: webhook callback handler (conceptual)
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

11) Limits, concurrency, and queue: staying reliable under load

Production media generation has three separate “capacity constraints” that you should design for: rate limits (requests per time window), concurrency (how many jobs run at once), and a queue (what happens when you exceed concurrency and jobs must wait). Leonardo documents these concepts explicitly and provides a dedicated limits reference and guide.

Best practices for limits

• Implement backoff on rate limit errors (exponential + jitter).
• Cap concurrency in your own worker pool rather than letting the API queue grow unbounded.
• Batch thoughtfully: spread generation requests across time; don’t spike thousands at once.
• Use webhooks to avoid tight polling loops that waste rate limit budget.
• Show user states: “Generating”, “Queued”, “Finalizing”, “Failed” with helpful actions.

12) Pricing: pay-as-you-go, credits, and cost planning

Leonardo positions API access as pay-as-you-go and encourages developers to start quickly, pay only for usage, and scale when ready. In practical terms, this means you should design your app with cost visibility and cost controls built in: per-user quotas, predictable default settings, and cost-aware UX.

13) Official SDKs: TypeScript and Python

Leonardo provides official SDKs for TypeScript and Python. SDKs typically wrap the REST endpoints, help with request typing, and standardize auth and errors. If you’re building a Node.js or Python backend, using an official SDK can speed up integration and reduce mistakes.

SDK usage pattern (recommended)

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

14) Production architecture: how to ship Leonardo API features that don’t break

The “hard part” of AI media generation 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. Here are architecture patterns that work well for Leonardo-style asynchronous generation APIs.

Reference architecture (battle-tested)

Idempotency: preventing duplicate generations

Duplicate generations are a major hidden cost driver. They happen when users click “Generate” multiple times or when your frontend retries on network timeouts. Solve this by generating a request hash from your parameters and storing a record: if the same user submits the same request within a time window, return the existing generation instead of creating a new one.

// Example: deterministic request hash concept
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 that keep apps safe and affordable

• Parameter caps: max images, max resolution, max video duration.
• Per-user quotas: daily credit budget; plan-based limits.
• Content policy: block obviously disallowed prompts; handle unsafe outputs per your product policy.
• Queue-aware UX: show status; do not encourage repeated clicks.
• Backoff policies: on rate limit errors, slow down rather than hammering the API.

15) FAQ: Leonardo API

References (official Leonardo docs)

For the most accurate and current parameter lists, request/response schemas, and feature availability, always confirm directly in the official docs below.