Leanado Ai

Leonardo Ai’s API Integration to build something awesome !

Kudos on taking the first step towards harnessing the capabilities of Leonardo.Ai's Production API! No matter the scale of your endeavor, from individual passion projects to services impacting millions, our Production API is designed to support your creative journey.
Here, we begin by guiding you through the creation of your API key. This key will unlock the potential to craft your initial image creations using the API. Let's dive in!

Create an account
No credit card required


Required Steps

Leonardo AI Production API
First things first, you'll need to access the Leonardo web application. If you're not already a user, sign up for a Leonardo account. Remember, a subscription to the Leonardo web app isn't required for API usage. The API offers its own distinct subscription plans, which we will explore in the following steps.


Guidance and Support Resources

Leonardo AI Production API
Please be aware as you navigate our guides and API documentation that comprehensive FAQs and detailed insights about the Leonardo platform can be found in our Help Center.
Should you require assistance, we invite you to contact us through the support widget, conveniently located at the bottom right corner of the Leonardo web app. Our team is ready to assist you at any time.


Create your API key

An API key can be obtained directly through the Leonardo.Ai web application interface.

Subscribe to an API Plan

Go to the 'API Access' section within the Leonardo web application. Select 'Subscribe to API Plan' to view and choose from the available subscription options.
Leonardo AI - Subscribe to an API Plan
Select the API plan that best fits your needs: API Basic, API Standard, API Pro, or reach out to us for a Custom Plan tailored to your requirements. Acquiring an API plan grants you programmatic access to the Leonardo.Ai platform.
Important to Remember:
API plans are distinct from web-app subscriptions like Free, Apprentice, Artisan, and Maestro.
An API plan provides access to the Leonardo Production API for developing applications, while a web-app subscription permits use of features within the Leonardo.Ai web and mobile applications, along with the User API.

Provision an API key

Once you have chosen an API plan, you'll be directed to the API Access Page. Begin by generating your inaugural API key; simply click on the 'Create New Key' button to get started.
Leonardo AI - Provision an API key
Start by naming your API key and, if you wish, providing details for an optional webhook callback. With a webhook in place, Leonardo.Ai will alert you once your image generation is complete and the output is ready to be retrieved.
Leonardo AI - Provision an API key

API Key Management Guidelines

01. Keep the number of API keys to a minimum for streamlined oversight.
02. Adopt a consistent naming convention for API keys that reflects their usage, such as by application name, environment, or team (e.g., mywebapp-dev, mywebapp-prod, myiosapp-dev).
03. Utilize the webhook callback function for efficient notifications upon completion of generations, thus avoiding the need for constant polling.

Test the API key

Navigate to the 'Get User Information' section within the API documentation. Enter your API key into the 'Bearer' field provided and select 'Try It' to conduct a test verification of your API key.
Leonardo AI - Test the API key

API Integration Troubleshooting Guide

If you're new to the Leonardo.Ai API and run into integration problems, consult this compilation of frequent errors for troubleshooting guidance. Should difficulties persist, reach out to Leonardo.Ai support for additional help.

Invalid response from authorization hook

{ "error": "Invalid response from authorization hook", "path": "$", "code": "unexpected" }
Check if your API key follows a valid UUID format.
Ensure that the API key you are using is accurate.
Verify that the API key is properly configured in your request header. It should be included as follows: Authorization: Bearer YOUR_API_KEY_HERE.
For instance, if you're utilizing the curl command to make a request:
curl --request POST \ --url https://cloud.leonardo.ai/api/rest/v1/generations \ --header 'accept: application/json' \ --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \ --header 'content-type: application/json' \ --data ' { "height": 512, "modelId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "prompt": "An oil painting of a cat", "width": 512 }

Authentication hook unauthorized this request

{ "error": "Authentication hook unauthorized this request", "path": "$", "code": "access-denied" }
If you receive an invalid response from the authorization hook, ensure that your API key is properly set. It must be included in the request header in the following format: Authorization: Bearer YOUR_API_KEY_HERE.

Invalid file extension

{ "error": "invalid file extension", "path": "$", "code": "unexpected" }
In the Upload Init Image API, the extension parameter refers to the file format of the image you're uploading, such as png, jpg, jpeg, or webp. It's not for the full filename or the image data itself.
After calling this API, you'll receive a presigned URL for the image upload. For step-by-step instructions on how to use this presigned URL, please refer to the guide titled "How to Upload an Image Using a Presigned URL.

Expected a boolean for type Boolean but found a string

{ "error": "expected a boolean for type 'Boolean', but found a string", "path": "$.selectionSet.sdGenerationJob.args.arg1.photoReal", "code": "validation-failed" }
Ensure that your code is assigning a Boolean value to your input rather than converting it into a string. The valid inputs are true or false without quotation marks. Including "true" or "false" within quotes can cause them to be misinterpreted as strings rather than Boolean values.

Photoreal mode, unexpected model id provided

{ "error": "photoreal mode, unexpected model id provided", "path": "$", "code": "unexpected" }
When enabling photoReal by setting it to true, there's no need to include the modelId parameter in your request. Simply omit the modelId parameter when utilizing photoReal.

Unexpected variable

{ "error": "Unexpected variable sd_Version", "path": "$", "code": "bad-request" }
Ensure that you are using the correct case for body parameters, as they are case-sensitive. For instance, the correct parameter is sd_version, not sd_Version. Using the latter may result in an unexpected variable error.

204 (No Content) when uploading an image

When successfully uploading an image using a presigned URL, a 204 status code is the indicator of success, and this response does not include any content. The image ID is not provided at this stage; it is actually obtained from the prior step when you call the Upload Init Image API. For instance, you will find the image ID in the previous response as uploadInitImage.id:
{ "uploadInitImage": { "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "fields": …, "key": …, "url": … } }

403 Forbidden error when uploading an image

While uploading an image using a presigned URL, you should omit any authentication-related headers such as the API key since they are not required for this operation. The presigned URL contains all the necessary permissions for the upload to proceed.

Couldn't access image

{ "error": "couldn't access image", "path": "$", "code": "unexpected" }
When employing APIs such as Create Upscale or Create Unzoom, you'll need to provide the ID of an image that has been previously generated on Leonardo.Ai. This specific image ID can be retrieved via the Get a Single Generation API, typically found in the response body as the first ID in the generated_images array, like so: generations_by_pk.generated_images[0].id.
{ "generations_by_pk": { "generated_images": [ { "url": …, "nsfw": …, "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "likeCount": …, "generated_image_variation_generics": [] }, ], … } }
At present, the feature to apply variations to images that have been uploaded through the Upload Init Image API is not available.

Failed to find init variation

{ "error": "failed to find init variation", "path": "$", "code": "unexpected" }
As with the 'Couldn't access image' issue, the image ID required is one that originates from Leonardo.Ai's image generation process, retrievable through the Get a Single Generation API. Please note that at this time, applying variations to images uploaded via the Upload Init Image API is not supported.

Invalid init image id

{ "error": "invalid init image id", "path": "$", "code": "unexpected" }
Ensure your init image ID is in the correct UUID format. The 'init_image_id' parameter requires an image ID provided by the Upload Init Image API. If you want to use an image created within Leonardo.Ai as the initial image, you must input its specific image ID into the 'init_generation_image_id' parameter.

200 Success but image URL array is empty

If the Get a Single Generation API endpoint is giving a 200 success status but the array generations_by_pk.generated_images[] is empty without any image URLs, perform the following checks:
  1. Inspect the response body for the "status" attribute to determine if the value is "COMPLETE". The endpoint provides a generations_by_pk.status attribute, where a status of "COMPLETE" indicates the image generation process has finished successfully.
  2. Recognize that image generation isn't immediate. Ensure there's a sufficient time gap after initiating an image generation request before attempting to retrieve the images. For User API integrations, implement a retry mechanism with exponential backoff. If you're using the Production API, set up a webhook callback while creating your API key; this webhook will alert you when your images are ready to be fetched.

Key Creation Error Occurred

If you encounter a "Key Creation Error Occurred" message when trying to generate a Production API key with a webhook callback, ensure the following:
  1. Confirm that your webhook callback URL is using HTTPS, not HTTP. The platform typically requires secure connections for callbacks, which is why an HTTP URL may trigger the error.
  2. If you notice a console error stating "WebhookCallbackUrl is not a valid url," this is likely due to the use of an HTTP URL. Switch to HTTPS to resolve this issue.
{ "errors": [ { "message": "WebhookCallbackUrl is not a valid url (must be https://)", "extensions": { "path": "$", "code": "unexpected" } } ] }

Failed to find init variation

{ "error": "failed to find init variation", "path": "$", "code": "unexpected" }
In variation API endpoints such as unzoom and no background, the isVariation parameter indicates whether the provided image ID was generated through a prior variation process.
  1. To apply a variation like no background to an image that was previously modified using another variation API (e.g., upscale), you should set isVariation to true.
  2. If the image ID was not produced by a prior variation, either set isVariation to false or omit the parameter entirely.

API Integration FAQ

How do you set the style like Creative, Dynamic, and Photography?

Incorporate the presetStyle parameter in the Create a Generation of Images API to dictate the styling preference.
  • For the photoReal pipeline active, assign presetStyle as CINEMATIC, CREATIVE, VIBRANT, or NONE.
  • If alchemy is off, presetStyle should be LEONARDO or NONE.
  • When utilizing alchemy, set presetStyle to one of the following options as per the desired outcome: ANIME, CREATIVE, DYNAMIC, ENVIRONMENT, GENERAL, ILLUSTRATION, PHOTOGRAPHY, RAYTRACED, RENDER_3D, SKETCH_BW, SKETCH_COLOR, or opt for NONE for no specific preset.

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

In the Leonard App, proceed to the 'Finetune Models' section. Select the 'Platform Models' tab, then choose and click on the desired model. Next, click on 'View More' to display the Model ID for the selected model.
Leonardo AI - API Integration

Can I use my custom model with the Leonardo API?

Yes, this is supported.

How do I find the model ID of my custom model?

In the Leonard App, go to the 'Finetune Models' feature. Select the 'Your Models' tab and then choose the model you're interested in. Click on the model and select 'View More' to display the specific Model ID for that custom model.

How do I upload an image for image to image?

Utilize the Upload Init Image API to upload your image. Upon completion, you will receive an image ID. Input this image ID into the 'init_image_id' parameter when calling the Create a Generation of Images API.

How to upload an image for image prompt?

To incorporate images into your prompts, utilize the Upload Init Image API to first upload your desired images. Upon completion, this endpoint provides you with an image ID for each uploaded image. You can then use these image IDs within the 'imagePrompts' parameter when invoking the Create a Generation of Images API.
The 'imagePrompts' parameter is designed to accept a list of image IDs formatted as a string array.
Here are examples of how to use 'imagePrompts' with one or more image IDs:
For a single image prompt: "imagePrompts": ["XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX1"]
For multiple image prompts: "imagePrompts": ["XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX111", "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX222"]

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

The 'extension' parameter in the Upload Init Image API specifies the file format of the image you wish to upload, accepting only recognized image extensions such as 'png', 'jpg', 'jpeg', or 'webp'. It is important to note that this parameter requires only the file extension, not the entire filename or binary image data.

How do I upscale an image via API?

Use the Variation: Create Upscale API.

What’s the difference between init_generation_image_id versus init_image_id?

The parameter init_generation_image_id is designated for inputting the unique image ID of a creation that was generated using Leonardo.AI. This image ID is typically provided to you as part of the output from APIs such as 'Get Generations by User ID' and 'Get a Single Generation.'

Why is the guidance scale fixed to 7 or lower even when I’m specifying higher?

When using the LEONARDO scheduler, it's advisable to maintain the guidance scale at 7 or below, as the scheduler configuration will take precedence over the guidance scale value you've set.

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

To enable RAW mode in Prompt Magic V3, adjust the highContrast parameter to false. Setting "highContrast": false equates to activating RAW mode within the Leonardo application.

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

To adjust the resonance level in Alchemy, modify the guidance_scale parameter. This parameter corresponds to the resonance setting found in the user interface.

How often should I be polling for image generations?

For optimal efficiency, configure your webhook callback, allowing Leonardo.Ai to alert you when your generation is ready for retrieval. Establish your webhook callback URL and security credentials during the creation of a new Leonardo.Ai Production API key.
Leonardo AI - API Integration

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

To top up credits, access the Leonardo.Ai app, select 'API Access' from the left-side menu, proceed to the 'Production API' tab, and click on the 'Top-up Credits' button.
Leonardo AI - API Integration

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

To obtain image IDs, utilize the API endpoints 'Get a Single Generation' and 'Get Generations by User ID.' These will provide you with an array containing URL links to images, each accompanied by an 'id' attribute which represents the image ID.

Do API Credits expire?

API Credits are non-expiring; they remain valid as long as your API Plan Subscription is active.

Why is my guidance scale setting not reflected?

The guidance scale parameter is pivotal in Leonardo's operations, with a recommended default of 7 for typical use cases. Here's a concise outline of its operational logic and constraints:
  • By default, the guidance scale is preset to 7 if not manually adjusted.
  • Without Alchemy, the guidance scale operates within a range of 1-20.
  • With Alchemy enabled, excluding the SDXL model, the scale extends from 2 to 30.
  • When the LEONARDO scheduler is active without Alchemy, the guidance scale cannot exceed 7.
  • For User API interactions on the Artisan or Maestro plan without sufficient tokens (thereby placing you in the slow queue), the guidance scale is also limited to a maximum of 7.

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

The output resolution may surpass the input resolution when utilizing Alchemy in combination with the high-resolution feature, potentially enhancing the output by factors like 1.5x, 1.75x, or 2x, courtesy of the integrated upscaling functionality. This discrepancy between input and output resolutions can be monitored and verified within the Leonardo web app interface.
Leonardo AI - API Integration

Meet Leonardo.Ai


Create stunning game assets with the help of AI.

Signup for exclusive early-bird access: