Answers to frequently asked questions when integrating to Leonardo.Ai via API


Is Leonardo Phoenix available on the API?

Leonardo Phoenix is not yet available on the API. If you are interested in API access, please contact us. Please include the following details in your contact:

  • Detailed use case for Leonardo Phoenix
  • Link to your website explaining your product
  • Volume of images you want to create

Where do I find the model ID of a specific platform model?

To find Leonardo.Ai's platform model IDs, use this List Platform Models endpoint to list out all Platform models. You'll find all the public models available with the id, name and description.

Another way is to navigate to the Leonard App, and select Finetune Models. Click on the Platform Models tab. Click on the model, then click on View More. This should reveal the Model ID of that particular model.

What is the model ID of PhotoReal?

PhotoReal v1 does not have a model ID.

To use PhotoReal on the Production API, you need to remove the modelId parameter and enable the photoReal flag.

For an example, check out the Generate Images Using PhotoReal sample recipe.

PhotoReal v2 requires Leonardo Kino XL, Leonardo Diffusion XL or Leonardo Vision XL models. See here for a sample request.

Can I use my custom model with the Leonardo API?

Yes, you can use your own custom model with the Leonardo API.

How do I find my custom model ID?

On the Leonard App, navigate to the Finetune Models. Click on the Your Models tab. Click on the model, then click on View More. This should reveal the Model ID of that particular custom model.

Generating Images

How do I specify the number of Images in my generation?

Use the parameter "num_images"in your API body. For example, to generate 1 image only, your API body could look like this

  "height": 512,
  "modelId": "6bef9f1b-29cb-40c7-b9df-32b51c1f67d3",
  "prompt": "An oil painting of a cat",
  "width": 512,
  "num_images": 1

How often should I be polling for image generations?

Instead of polling, the best practice is to set your webhook callback so that Leonardo.Ai can notify you when to fetch your generation.

You can set your webhook callback URL and authentication details when creating a new Leonardo.Ai Production API key.

How do I use Alchemy v2 on the API?

Alchemy V2 works with SDXL models like Leonardo Vision XL, Leonardo Diffusion XL, AlbedoBase XL and KinoXL. To use Alchemy v2, choose an SDXL model and simply set the alchemy parameter to true. This setup will use Alchemy v2.

Do my images expire after generating via the API?

No, images generated via the Leonardo.Ai API will not expire and can also be accessed from the Web App at any time.

Why is my guidance scale setting not reflected?

The guidance scale is an advanced parameter and Leonardo advises to use a guidance scale of 7 in most cases.

There are some default behaviours and conditions applied when trying to control the guidance scale. The conditions and logic are as follows:

  • If not set, guidance scale default is 7.
  • If not using Alchemy, guidance scale is limited to 1-20.
  • If using Alchemy but not using an SDXL model, guidance scale is limited to 2-30.
  • If not using Alchemy and scheduler is set to LEONARDO, guidance scale is capped at 7.

How do you set Prompt Magic V3 to RAW mode using the API?

To set Prompt Magic V3 to RAW mode, set"highContrast": false. This is similar to enabling RAW mode on the Leonardo app.

How do you set Alchemy's Resonance using the API?

To set Alchemy's resonance, use the guidance_scale parameter. This controls the resonance setting on the UI.

Why is the output image bigger than the height and width I specified?

The input resolution is not always equal to the output resolution. When you use Alchemy and high resolution, the output resolution could be bigger by 1.5x, 1.75x, 2x, etc. compared to the input resolution due to upscaling built in to this features. For example, when using Alchemy v2, the output dimension is 1.75 times bigger. When using Alchemy v1, the output is 1.5 times bigger. When using Alchemy v1 and high resolution, the output is twice the input.

To check, you can observe this in the Leonardo web app as the following image.

Generating Motion

Why am I seeing Service Error when generating SVD motion?

Although Service Erroris a generic error message, in this scenario, the error is commonly due to incorrect IDs being used. Ensure that the ID is not the generationIdfrom the Create a Generation of Images API., but rather the Image Id from Get a Single Generation.. The generationId needs to be passed to Get a Single Generation. , and the returned image Id can then be used in the Create SVD Motion Generation API.

Uploading Images

How do I upload an image for image to image?

Use the Upload Init Image API. This endpoint will return an image ID that you input to init_image_id in the Create a Generation of Images API.. Ensure that if you are using init_image_id, that you also include isInitImage:true.

Follow this recipe for a step by step guide on uploading images to use with image to image guidance.

How to upload an image for image prompt?

Use the Upload Init Image API. This endpoint will return an image ID that you input to imagePrompts in the Create a Generation of Images API.

Follow this recipe for a step by step guide on using image prompts.

Note: that the parameter imagePrompts accepts an array of image IDs as a string.

Example 1: One image prompt:


Example 2: Two image prompts:


What is the extension parameter in the Upload Init Image API?

The extension parameter in the Upload Init Image API is the file extension of the image you want to upload. Examples of file extensions are png, jpg, jpeg, or webp only. The extension parameter will not accept the full filename or some binarized image data.

What’s the difference between init_generation_image_id versus init_image_id?

init_generation_image_id accepts the image ID of images generated on Leonardo.Ai. These image IDs are returned by API endpoints like the Get Generations by User ID and Get a Single Generation.

init_image_id accepts the image ID returned by the Upload Init Image API endpoint.


How do I upscale an image via API?

To upscale an image via API, use the Variation: Create Upscale API. This Upscale will apply 'Creative Upscale' to your image.

How do I get the image ID for transforming like upscale and unzoom?

You can get the image IDs via the Get a Single Generation or Get generations by user ID API endpoints. These return an array of URL links to images together with an id attribute. Thatidattribute is the image ID.

API Credits

Why is the cost of generating images different using API credits vs Web Tokens?

Charges are calculated differently for API calls compared to generating using Web Tokens from the Web App, resulting in variations in costs. Additionally, API credits do not expire, whereas Subscription Tokens have a limited validity period.

How do I top up my API plan with more API credits?

You can buy instant top up API credits via the Leonardo.Ai app. Navigate to API Access on the left side menu, click on Production API tab, and click on the Top-up Credits button.

Do API Credits expire?

No, API Credits do not expire. However, note that you can only use your API credits when you have an active API Plan Subscription.

I still have credits why can't I make anymore API calls?

Please ensure your API plan is active as you won't be able to access your credits without being on an API Plan.

My API credit balance is negative, is that normal?

Yes, it's normal for API credits to go negative.

Blocking your usage once you run out of API credits is not a precise process. There are expected ways you could get to negative but our system won't let you get too far with a negative API credit balance.

Note that the negative API credits will be deducted from the next API credit top-up. To avoid running out of credits, plan your usage or set up auto top-ups.

Where is the API credits pricing calculator?

The API pricing calculator is temporarily unavailable at the moment due to enhancements in progress and will be up and running soon. You can view here for estimated API credit costs and plan your usage.

Do I still get charged credits if my generation failed?

If you got charged credits but your generations failed via API, the credits will get refunded back into your account.

How do I find the invoice for my API subscription plan?

We use Paddle.com for our payment system, please head over to https://paddle.net/ and enter your email to locate your receipt. A copy of your invoice would also have been sent to your email automatically after payment.

Other Questions

Does Leonardo have official SDKs?

The following are Leonardo.Ai's official SDKs.

  1. Python SDK
  2. TypeScript SDK

Where did the User API key go?

The User API key is now a deprecated feature and has been replaced by the Production API key. This key can be used for all API endpoints and can be generated here. Existing User API keys still work, but new ones need to be generated as Production API keys.