A Python application can request Leonardo.Ai images through an API instead of relying on a person to create each image in the web interface. That shift helps developers build a repeatable visual-content workflow for apps, websites, and other digital products. You can set up access, send a request, and handle the result in Python. Asynchronous generation means an image request runs in the background and returns a result after the job finishes. This beginner-friendly path starts with account setup and leads to a generated image your application can use. You will see where to find tools, how to send a request, and how to check its status. The first useful milestone is a successful request that returns a generationId.
Key Takeaways
- Use the API to connect image creation to a Python application.
- Fund API use separately from a web-app subscription.
- Keep your Production API key on a server you control.
- Choose a model ID and request settings before sending a job.
- Wait for the job to finish before using its image URLs.
Leonardo AI API: Features and Integration Guide for Developers
Developers can use the API for image generation and image-to-image workflows, then connect those capabilities to an application. The REST interface lets your code send creative requests without relying on a person to work through the web interface.
Use the API for repeatable, app-driven tasks, and use the web interface for hands-on creation and review. This distinction helps you decide where each part of a visual workflow belongs.
The API is built for requests your application can run in a repeatable workflow.
Image generation and image-based workflows
Text-to-image requests turn a written prompt into one or more images. Image-to-image requests use an uploaded image to guide a new result, such as a change in style, color, or composition.
These options can support product mockups, social content, or visual assets made inside another tool. For broader context on available creative tools, see this guide to AI image generators for different workflows.
SDKs and code export
Leonardo.Ai lists official Python and TypeScript SDKs for connecting code to its services. You can also use Get API Code in the web app to export API code for image or video generations.
The Leonardo API documentation helps you check model requirements and endpoint parameters before coding. Video generation is available as another API capability, but its job flow needs separate settings and handling.
Get API Code can reveal how a working request maps to the app’s controls. Use Get API Code to inspect the parameters behind a working web-app generation before translating that request into Python.
How Does Leonardo AI API Pricing Work?
Leonardo.Ai API use is billed separately from a free or paid web-app subscription, through API credits. Separate API credits fund requests, and usage comes out of the API credit balance as requests run.
A Leonardo web app subscription does not pay for API usage. Pay-As-You-Go has no upfront commitment or monthly fee, and API credit balances do not expire.
The pricing calculator estimates request costs based on the model and selected features. Its estimate changes with resolution and the number of images, so match the settings to your planned batch.
Leonardo AI API pricing can be estimated before a request, then checked against the response after generation. A response includes a cost object with the amount charged and its unit; apiCreditCost remains available during the pricing transition.
Top up credits manually or set automatic top-ups in API Access. You can choose a balance threshold and top-up amount, then edit or disable automatic top-ups there.
Requests pause when the balance reaches zero, and they resume after you add credits. High-volume users, customers who need dedicated infrastructure, or teams seeking custom per-model discounts can ask Leonardo.Ai about custom pricing.
Set an automatic top-up threshold that leaves enough balance for expected request volume without allowing an unchecked spend.
How Do You Create and Secure a Leonardo API Key?
A Leonardo API key is created from API Access in the web app, and new keys must use the Production API key type. Production keys are required for new access because User API keys are deprecated.
The API key grants access, but API requests still need separately funded API credits. An account can have up to 10 API keys, and existing User API keys still work.
- Sign in to the Leonardo web app.
- Open API Access.
- Create a Production API key and give it a clear name.
- Add a webhook callback URL if your workflow needs one.
Send the credential in an Authorization: Bearer API-key header with each API call. Store it in a server-side environment variable, not browser-side code that users can inspect.
A browser app can expose any key placed in its code or network requests. Keep the key on a server you control and replace it if it is exposed.
How Do You Generate Images With Python?
A first Python request needs the generation endpoint, a Bearer key, and a JSON body containing a prompt and valid modelId. Asynchronous generation means the request can return before the image job finishes.
Send the request to POST https://cloud.leonardo.ai/api/rest/v1/generations and save its generationId. The response gives your code the identifier needed to check the job.
Prepare the request and credentials
The quick-start settings below give you a concrete starting point, not a rule for every model. Change the prompt to describe the image you want, and confirm that your model supports the chosen options.
| Field | Quick-start value | Purpose |
|---|---|---|
| modelId | 7b592283-e8a7-4c5a-9ba6-d18c31f258b9 | Selects the model |
| width and height | 1920 by 1080 | Sets image dimensions |
| num_images | 4 | Sets the output count |
| contrast | 3.5 | Sets image contrast |
| alchemy and ultra | false and false | Turns both options off |
Submit the job and wait for its status
The num_images field controls how many outputs the request asks for. This Python example submits a job, then checks its status until it completes or fails.
import time; import requests
url = “https://cloud.leonardo.ai/api/rest/v1/generations”
headers = {“Authorization”: “Bearer ” + API_KEY, “Content-Type”: “application/json”}
payload = {“prompt”: “A red fox in a snowy forest”, “modelId”: “7b592283-e8a7-4c5a-9ba6-d18c31f258b9”, “width”: 1920, “height”: 1080, “num_images”: 4, “contrast”: 3.5, “alchemy”: False, “ultra”: False}
result = requests.post(url, headers=headers, json=payload).json()
generation_id = result[“sdGenerationJob”][“generationId”]
status_url = url + “/” + generation_id
while True:
job = requests.get(status_url, headers=headers).json()[“generations_by_pk”]
if job[“status”] in (“COMPLETE”, “FAILED”): break
time.sleep(5)
A job can return PENDING with an empty generated_images array while work continues. Use the generation endpoint or Get a Single Generation endpoint to retrieve status by generationId. Treat PENDING as a job still in progress and stop polling only when its status is COMPLETE or FAILED.
How Do You Choose a Model and Tune an Image Request?
Start model selection by retrieving the available platform model IDs rather than copying a model name into modelId. Use an ID in the request, since a display name is not the required value.
Check a model’s requirements before combining request settings. Public platform models and custom models may use different names, options, or limits.
GET /platform-models returns public model IDs, names, and descriptions. For one model, GET /models/{id} returns its details; GET /me returns current-user information and usage.
| Request | Response | Use |
|---|---|---|
| GET /platform-models | Public IDs, names, descriptions | Browse platform models |
| GET /models/{id} | Details for one model | Check a selected model |
| GET /me | Current-user information and usage | Review account details |
For a custom model, find its ID in the Finetune Models section of the app. A model name may help you choose, but the ID is what your request needs.
Prompt text describes the scene and its visual elements. The styleUUID, contrast, alchemy, and ultra fields add controls, though each model may support different combinations.
Prompt choices can shape subject, setting, lighting, and mood. This comparison of free text-to-image tools offers more context for testing styles and results.
Model-specific guides can list controls that do not apply across every model. For example, the Kino XL API reference describes settings for that model, including Alchemy and image guidance.
Verify the model ID and compatible settings before sending a large batch.
How Do You Retrieve, Upscale, and Reuse Images?
Once a generation completes, use its returned image URLs in the next stage of your product workflow. Completed outputs remain available through the API and the web app.
Leonardo API-generated images do not expire and may be used commercially subject to the Terms of Service. The terms set the limits, so do not assume every use is allowed.
Choose a next step based on what your product needs:
- Retrieve the output URLs and send them to your app.
- Open generated images in the Leonardo web app.
- Use the Variation: Create Upscale endpoint for Creative Upscale.
- Upload a source image to guide image-to-image generation.
Upload Init Image returns an image ID for an uploaded source. The imagePrompts field accepts an array of image IDs as strings, which lets a request use uploaded images as references.
Commercial use depends on the Terms of Service, not just the fact that an image came from an API. Read this beginner’s overview of Leonardo.Ai for more context on its tools and terms.
Match each uploaded file to a supported extension, png, jpg, jpeg, or webp, before sending it.
Can You Automate Leonardo API Workflows Beyond Python?
A no-code workflow can connect prompt creation, Leonardo generation, and file storage without changing the underlying API job process. Automation works best when each step has a clear input and output.
Build a workflow that waits for a completed job before passing its files onward. This keeps later steps from trying to use an image that is not ready.
- Create or supply a prompt.
- Call Leonardo image generation.
- Wait for completion or use a callback.
- Send the result to storage or another app.
For example, a Make.com scenario can use ChatGPT to create prompts, call Leonardo generation, then download and upload results to Google Drive.
An image-to-video workflow can upload a still image, submit motion settings, retrieve the clip, and save it to storage. That connects image video creation to the same broader content workflow.
Test one complete workflow with a single output before scheduling repeated runs.
Teams already using coding agents may also connect tools through MCP. This comparison of coding agents explains how agent tools can work with outside services.
Conclusion
A small test request is the clearest way to start a Leonardo API integration. It lets you see whether the selected model and settings produce an image your application can use.
Inspect the returned image and cost before increasing request volume. Then adjust the prompt or settings based on the result, rather than sending a large batch with untested choices.
Keep the first workflow simple: one prompt, one model, and one output. That gives you a clear result to compare when you add more settings or connect another tool.
Run one carefully configured test generation, inspect its output and cost, then build that request into your application.
FAQ
Can I use Leonardo API images commercially?
Yes, Leonardo API-generated images may be used commercially subject to Leonardo’s Terms of Service. The terms govern which uses are allowed, so check them for your project and intended audience. The fact that an image came from a paid request does not, by itself, grant rights beyond those terms. Keep the applicable terms in mind when you plan to publish or sell work.
Are uploaded images used to train Leonardo models?
No, uploaded input images are used to influence the specific request, not to train Leonardo models. They can guide the output’s subject, style, or composition for that job. This use is different from adding an image to a training set. If an image contains sensitive material, review the platform’s terms and privacy details before sending it.
Can I delete an image uploaded for image-to-image generation?
Yes, you can delete an image uploaded for image-to-image generation by using the Delete Init Image API endpoint. Keep the image ID returned during upload so your application can identify the right source image. Deleting an uploaded source is separate from handling generated output URLs. Add the delete call to your workflow when the source image no longer needs to remain available.
Can I make generated images private?
Yes, set public to false when you create the generation to make its images private. Include that setting in the generation request rather than changing it after the job runs. Privacy settings can matter when outputs belong to a client project or internal product work. Check the request’s other options before sending it, so the generation uses the visibility you intend.
Can coding agents use Leonardo’s API?
Yes, coding agents can work with Leonardo’s API through Leonardo’s MCP server. MCP lets compatible agents connect to tools and services, including agents such as Claude and Cursor. This can support tasks that involve preparing requests or working with API results. The agent still needs access to the right API tools and credentials, so control where those credentials are stored and used.
