Leonardo AI API: Setup and First Request

The Leonardo AI API turns image generation into a job your app can submit and track. The key choice comes first: do you need Leonardo's image workflow, or will your product later need video and music too?

Use these steps to define the job, create a secure token, send a request, read the result, and decide when Apiframe is a better fit for a wider media pipeline.

Step 1: Define Your Leonardo AI API Workflow

Before you write code for the Leonardo AI API, write down the exact generation path your product needs. A clear job flow keeps you from wiring up a simple demo that later needs to grow into a system with uploads, queues, retries, or webhooks.

Start with one narrow task. For example, your app might turn a product description into a square marketing image. Another app may take a user-uploaded photo and apply an edit. Those are different workflows, even though both produce an image.

Pick the input and output

Choose one of these starting points:

• Text to image: send a prompt and receive generated image results.
• Image to image: use an existing image as a starting point.
• Inpainting: send an image plus a mask that marks the area to change.
• Upscaling: submit an image when you need a larger or sharper result.
• Text to video: use a prompt when motion is part of the product flow.

The workflow is job based. You submit a generation, wait for processing, then retrieve the output and its metadata. For larger jobs, plan for a webhook or a background worker that can check in without keeping a user's browser open.

Also decide where the request runs. Keep it on your server, not in browser code. The server can protect the token, limit user requests, store job IDs, and apply your own usage rules.

Leonardo's model list can change, so don't hard-code a model ID without checking the current reference. If your wider product plan includes several media types, compare this workflow with our AI image API guide before you commit to one provider.

Key takeaway: Treat image generation as an asynchronous job. Define the input, output, user wait time, and failure path before sending your first request.

Step 2: Create Access Credentials and Review the API Docs

Access to the Leonardo AI API starts with an API key and a review of the current endpoint docs. Keep this step separate from your application code so you can change models or rotate keys without a rushed release.

Create a server-side key

Open the provider's developer dashboard and find the API access area. Create a key for your development environment, and give it a name that tells you where it belongs, such as a development or production label.

Save the key in an environment variable or a secret store. Don't paste it into a frontend bundle, a public repository, a screen recording, or a client-side mobile app. If a key leaks, revoke it and issue a replacement.

The Production API uses a bearer token. A request header follows this pattern:

Authorization: Bearer YOUR_API_KEY

The reference base path is the cloud API under its versioned API route. Read the current endpoint page before coding because model IDs, request fields, and supported features can change.

Read the request shape

Find the generation endpoint first. Note the required prompt field, the model field, image dimensions, image count, and any guidance or negative prompt settings. Don't copy every optional field into your first call. A small request is easier to debug.

Then find the result endpoint. You need the response field that carries the generation ID, plus the status values returned while the job runs. Check how completed outputs are represented, since some APIs return image URLs in a later response rather than the first one.

You can review the API error documentation before building retry logic. A bad request should not be retried forever, while a temporary service or queue issue may deserve another attempt.

Write down these values in your project notes:

• API base path
• Generation endpoint
• Result lookup endpoint
• Authentication header
• Required request fields
• Terminal success and failure states

By now, you should have a private development key and a short request map. You don't need a full production setup yet. You need enough detail to send one controlled job.

Step 3: Send Your First Image Generation Request

Your first Leonardo AI API call should be small, repeatable, and easy to inspect. Use one prompt, one model ID from the current docs, and a modest output size while you verify the request path.

Build the request

Use a backend script or a command-line client. The exact endpoint and field names must match the current Leonardo reference, so treat this shape as a pattern rather than a copy-paste template.

curl -X POST "API_BASE_PATH/generations" \ -H "Authorization: Bearer $LEONARDO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "A small red cabin beside a quiet alpine lake at sunrise", "modelId": "CURRENT_MODEL_ID", "width": 1024, "height": 1024 }'

Replace the model placeholder with an ID returned by the current model listing or shown in the docs. Don't assume a model name is also a valid model ID. Providers often use separate display names and machine values.

Keep the first prompt plain. A scene with a subject, place, light, and style is enough to test the call. If the request fails, you want to know whether the problem is auth, JSON shape, model choice, or prompt content, and our Midjourney prompt guide covers similar prompt basics if you're new to writing them.

The create response should give you a job identifier or an equivalent generation record. Store that value right away. Your app should return a pending state to the user instead of waiting for the entire render inside the original web request.

Test one change at a time

Once the first job works, change one parameter. Try a new prompt before you change the model. Then test a different aspect ratio. This gives you a clean way to spot which field changed the result or caused the error.

Keep the raw request and response in your development logs, but redact the bearer token. Record the job ID, request time, selected model, status, and final image URL. Those fields will help when a user reports that an image is missing.

If you need reference images, don't send raw file bytes unless the docs say to do so. Leonardo upload flows may return presigned storage details. In that pattern, you request an upload, send the file to the temporary storage URL, then pass the returned image ID into the generation request.

For image edits, an inpainting flow also needs a mask. A soft mask can blend an edit into its surroundings. A hard mask can make a sharper boundary. Keep those as separate test cases because a mask can change the result more than a prompt tweak.

A common integration pattern is to authenticate, submit a generation, then retrieve its result. The current Leonardo generation reference should take priority when examples differ.

Pro Tip: Save a known-good request as a fixture. When you change SDK versions or model IDs, run that fixture first.

Step 4: Retrieve Results and Handle API Errors

The Leonardo AI API usually separates job creation from result retrieval. Your app needs to handle that gap cleanly, especially when a user is waiting for an image inside a product screen.

Poll without blocking the app

After the create call returns a job ID, poll the result endpoint at a measured interval. Stop when the job reaches a terminal state. A completed job should include output details such as image URLs or generation metadata.

Don't poll forever. Set a time limit for the user-facing request, then move long jobs to a background worker. Your worker can keep checking while the front end shows a pending state. If your account supports callbacks, use a webhook for long-running work and keep polling as a fallback.

Store the final result in your own record. Save the provider job ID beside your internal job ID. That mapping makes support work much easier because you can trace a customer action without exposing internal credentials.

Separate errors by type

• Authentication errors: check the key, header, and environment variable.
• Validation errors: inspect the JSON field names, values, and model ID.
• Rate or concurrency errors: slow the queue and retry with backoff.
• Service errors: retry a limited number of times, then show a useful message.
• Generation failures: mark the job failed and keep the provider message for logs.

Only retry errors that may clear on their own. Retrying a broken request adds load and hides the real bug. Use exponential backoff for temporary failures, with a maximum attempt count.

Leonardo's API also has separate capacity limits. Requests per time window, active jobs, and queued work can each affect delivery. Build a small queue rather than letting every user action hit the provider at once.

For cost control, record the model and output settings with each job. A low-cost preview path can serve the editor, while a final render can run only after the user approves the prompt.

Step 5: Connect Leonardo AI to Your Product with Apiframe

Leonardo is a sensible choice when your product is focused on image generation and its creator-oriented model library fits the job. To weigh that choice against other providers, compare current AI image generation APIs for model coverage, workflow, and integration effort. But the decision changes when your roadmap includes video or music.

Apiframe gives product teams one developer-facing API for AI image, video, and music generation. That means your application can keep one account pattern and one job flow while you test different media paths. Review the available AI media models on Apiframe before you hard-code a provider-specific design.

Keep your app behind one adapter

Even if you start with Leonardo, put provider calls behind a small internal service. Your front end should ask for a generation, not know which vendor handles it.

Your adapter can expose a common request such as:

generate({ mediaType: "image", prompt, model, options
})

Inside that service, map the common fields to the selected provider. Return your own job ID to the rest of the app. This keeps the UI stable when you switch models or add another media type.

For an Apiframe image flow, the same pattern applies: authenticate, send a POST request, receive a job ID, then poll the job or accept a webhook. Its unified design becomes more useful when a customer journey crosses media types. A user might generate a product image first, then request a short motion clip, then add music for a campaign draft.

That breadth has a trade-off. Leonardo's strength is its image and creator-tool focus. Apiframe's strength is the shared interface across media. Pick based on the product flow, not brand recognition alone.

Use Apiframe's API documentation when you want to compare the request pattern with your current adapter. If your team needs a single media layer across several features, Apiframe is the cleaner place to start. If your scope will stay image-only, keep the Leonardo integration narrow and well tested.

Key Takeaway: Put a provider adapter between your product and any media API. It protects your UI from model changes and makes a later move to multi-media generation much easier.

Conclusion

Start with one small Leonardo generation, keep the key on your server, and build result polling before adding advanced options. If your roadmap includes more than images, test the same job flow through Apiframe early. Next, save one known-good request and use it as the first integration test in your app.