The Leonardo AI API is the developer entry point to Leonardo.Ai’s image and video models. You POST a prompt to a REST endpoint, get back a generation ID, and pull the finished image down when it is ready. That is what turns a manual art tool into something a product can call a thousand times a day, and it is why Leonardo shows up on most shortlists of image APIs worth wiring into a real product.

This guide covers what the API returns, how authentication and polling work, what a generation costs, and where Leonardo sits next to the FLUX family and other hosted image endpoints. Everything below is written from the developer side, not the marketing page.

> Further reading: if you would rather compose image models as a visual graph and call the whole thing through one endpoint instead of wiring each provider yourself, Wireflow’s Leonardo AI API page walks through that setup with models like Nano Banana 2 running as workflow nodes.

What the Leonardo AI API actually does

Leonardo exposes its generation stack over REST at https://cloud.leonardo.ai/api/rest/v1. The core surface is text-to-image, image-to-image, and image-to-video, plus the supporting pieces that make Leonardo distinct from a bare model host: LoRA training on your own dataset, saved presets, upscaling, and background removal. You are calling a creative platform, not a single checkpoint, and that shows in the number of parameters each request accepts.

The practical consequence is that Leonardo is a good fit when your product needs a house style. Train or select a fine-tune once, reference its modelId on every call, and outputs stay recognisably yours. That is a different job from a general purpose text-to-image endpoint, which is closer to what people reach for when they compare content generation APIs on raw quality and price.

Video is the newer half of the surface. Image-to-video takes a still you already generated and animates it, which means the API can carry a project from prompt to moving asset without leaving the same credit balance. Teams already building multi-step generation chains tend to treat that as one stage in a longer pipeline rather than a standalone feature, the same way they chain REST calls into a single asset pipeline.

Getting a key and making the first call

API credits are separate from a web app subscription. You create an account, buy API credits, then generate a key from the API Access page in the Leonardo dashboard. The key goes in an authorization: Bearer <key> header and, as Leonardo’s own docs say plainly, never in client-side code. That split between consumer plan and developer balance is common across generation platforms built for developers, so budget for it separately.

A minimal generation request looks like this:

curl -X POST https://cloud.leonardo.ai/api/rest/v1/generations \
  -H "authorization: Bearer $LEONARDO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "a ceramic vase on a plain studio backdrop, soft key light",
    "modelId": "7b592283-e8a7-4c5a-9ba6-d18c31f258b9",
    "width": 1024,
    "height": 1024,
    "num_images": 2
  }'

The response does not contain an image. It contains a generationId. This trips up almost everyone on their first attempt, and it is the same asynchronous shape you see across hosted image endpoints, including the FLUX Pro API and its code examples.

Polling, webhooks, and getting the file back

Once you hold a generationId, you have two ways to collect the result. The simple one is polling: GET /generations/{id} on a short interval until the status flips to complete and the response carries image URLs. Two seconds between polls is usually enough, and you should cap the loop rather than let it spin forever on a failed job.

The better option for anything production shaped is a webhook. You register a callback URL when you create the key, and Leonardo posts to it when a generation finishes. That removes the polling loop, keeps your worker free, and matters a lot once you are firing many requests at once instead of one at a time, which is the same reason batch image generation over an API needs a queue rather than a for loop.

One detail worth planning for: generated image URLs are hosted by Leonardo and are not permanent. If the asset matters, download it and push it to your own storage as part of the same job that handles the webhook. Treat the API response as a handoff, not as a CDN, the same discipline you would apply to any of the orchestration APIs running in production apps.

What a generation costs

Leonardo bills API usage in credits that you buy up front, drawn down per generation. Cost per image is not one flat number. It moves with resolution, the number of images per request, and whether you enable the quality-boosting options like Alchemy or Ultra. A 512px draft and a 1536px Ultra render are not remotely the same line item.

The estimate that actually matters is cost per accepted image, not cost per generation. If you throw away three of every four renders, your real unit cost is four times the sticker. Building a tight prompt and a strict preset before you scale is the cheapest optimisation available, which is why prompt quality carries more weight in an API budget than most teams expect, and why prompt structure work pays for itself quickly.

How it compares to other image APIs

API	Best at	Async model	Distinguishing feature
Leonardo AI	House style via fine-tunes and presets	generationId plus polling or webhook	LoRA training, upscaling, image-to-video in one balance
FLUX 1.1 Pro	Prompt adherence and photoreal detail	Request then poll a result URL	Strong text rendering and composition control
Recraft V4	Vector, logo, and brand-consistent output	Sync or async depending on host	Native SVG and design-system output
Nano Banana 2	Fast iteration and editing passes	Job ID plus poll	Low latency, strong instruction editing

None of these is strictly better. Leonardo wins when consistency across thousands of assets is the requirement. If the requirement is raw fidelity on a one-off render, the FLUX 1.1 Pro model page is a more direct comparison point. For design system output where the deliverable is a vector rather than a raster, Recraft V4’s API examples show a different shape of job entirely.

The realistic answer for most teams is more than one provider. Leonardo for branded assets, something faster for drafts, something sharper for hero shots. That is a routing problem, and it is why platforms that sit above several image APIs exist at all.

A practical workflow: 200 product variants

Here is a concrete job. You have 40 products and want five lifestyle backgrounds each, consistent enough to sit in one catalogue. Draft the base prompt by hand or with a prompt generator first, because every one of the 200 renders inherits whatever you get wrong in it.

1. Pick or train one model and lock the modelId. Consistency comes from the model, not the prompt.
2. Write one prompt template with two slots: product description and background description. Do not hand-write 200 prompts.
3. Fire requests through a queue with a concurrency cap. Five to ten in flight is a sane starting point before you know your rate limits.
4. Take results on the webhook, download immediately, upload to your own bucket, and record the generationId alongside the stored file.
5. Run a cheap automated check before a human ever looks: resolution, file size, and a quick aesthetic score to drop obvious failures.

Step five is the one people skip, and it is where the cost per accepted image gets fixed. A five-line filter that rejects blank or malformed renders before review saves more time than any prompt tweak. The same discipline applies whichever model you route to, including the Nano Banana image generation API when you need faster turnaround on drafts.

FAQ

Is the Leonardo AI API free? No. API credits are purchased separately from any web app plan. New accounts typically get a small free credit allowance after adding a payment method for verification, which is enough to test the integration but not to run anything real. If budget is the constraint, the free image generator comparison is a better starting point.

Where do I get a Leonardo API key? From the API Access page inside the Leonardo dashboard at app.leonardo.ai/api-access. You can register a webhook URL on the same screen, which is worth doing at key creation time rather than retrofitting later.

Does the API return the image directly? No. It returns a generationId, and you fetch the finished image afterwards by polling GET /generations/{id} or by receiving a webhook callback. Any client written to expect an image in the first response will break, so design the job around the async shape described in this guide to building AI workflows with an API.

Can I use my own trained model through the API? Yes. Custom fine-tunes and LoRAs trained in Leonardo are addressable by ID in API calls, which is the main reason teams pick it over a plain text-to-image endpoint. Anyone weighing that tradeoff usually ends up reading a broad comparison of current image generators before committing.

How do I avoid rate limit errors at scale? Queue your requests with a concurrency cap instead of firing them in parallel, retry on 429 with exponential backoff, and use webhooks so a slow generation never blocks a worker slot.

Can the API generate video? Yes. Image-to-video is part of the same surface and draws from the same credit balance, so you can take a still you generated and animate it without adding another provider, though a dedicated video generator comparison is worth reading before you standardise on it.

Wrapping up

The Leonardo AI API is worth the integration when your requirement is consistent, branded output at volume rather than a single impressive render. The asynchronous shape, the credit model, and the fine-tune addressing are all straightforward once you accept that the first response is a receipt and not an image.

Build the boring parts first: a queue, a webhook handler, your own storage, and an automated reject filter. Those four pieces determine whether the API is cheap or expensive far more than the model you pick, and they carry over unchanged the day you decide to route half your traffic to a node-based platform with API access or a different provider entirely.