Leonardo API skill

Leonardo API skill is a free agent skill maintained by Scopeful. It teaches an AI coding agent such as Claude Code, Cursor, Windsurf or Codex how to drive this tool correctly, so you do not have to re-explain it every session. Every published Scopeful skill is free and the install command is public, with no sign-in required. Install it with Get an API key at leonardo.ai and set LEONARDO_API_KEY in env (no public SDK; use the REST API directly). Scopeful also tracks hand-verified USD pricing for 39 AI creative tools at https://www.scopeful.org/tools.

Drop-in Claude Code skill for the Leonardo API. Generate, refine, and download images without writing scripts. Your agent reads the skill once and follows it every time.

Tags: image, api, generation

Install

Get an API key at leonardo.ai and set LEONARDO_API_KEY in env (no public SDK; use the REST API directly)

Reference

name: leonardo description: Use this skill whenever the user wants to generate, refine, or upscale images using Leonardo.ai through its API or a coding agent. Triggers include "Leonardo", "Leonardo.ai", "generate an image with Leonardo", "upscale with Leonardo", or asking for high-quality image generation with specific control over models like Phoenix, Lucid, or FLUX.

Use Leonardo.ai for Image Generation

Leonardo.ai provides a powerful suite of image generation models (Phoenix, Lucid, FLUX) and advanced refinement tools (Ultra, Enhance Prompt, Upscalers). This skill teaches your agent how to use the Leonardo API effectively, manage generation tasks, and avoid common pitfalls with credits and parameters.

When to use Leonardo

Use Leonardo when the user wants:

• Advanced Image Control — High-quality output with fine-tuned models like Phoenix or Lucid.
• Ultra & Enhance Prompt — Enhanced rendering pipelines for cinematic or photorealistic results (replacing the older Alchemy/PhotoReal params).
• Specific Upscaling — Access to Leonardo's specialized upscalers (Universal, Creative).
• ControlNet / Image Guidance — Using an existing image to guide the shape, style, or pose of a new generation.
• Phoenix 2.0 Character Engine — Leveraging robust character consistency capabilities.

Do not reach for Leonardo when:

• The user wants simple, free generation (use a basic SDXL provider instead).
• The user is only iterating on text prompts (use a cheaper model for draft iterations before moving to Leonardo for final quality).

API Integration Basics

Leonardo uses an asynchronous task-based API. You don't get the image in the first response; you get a generationId.

1. Start a Generation

When generating, you should use the correct model UUIDs. Here are the common ones:

• Phoenix 1.0: de7d3faf-762f-48e0-b3b7-9d0ac3a3fcf3
• FLUX.1 Dev: b2614463-296c-462a-9586-aafdb8f00e36
• FLUX.1 Schnell: 1dd50843-d653-4516-a8e3-f0238ee453ff

// POST /v1/generations
const response = await fetch("https://cloud.leonardo.ai/api/rest/v1/generations", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "A neon-lit cyberpunk city street, raining, 35mm photography",
    modelId: "de7d3faf-762f-48e0-b3b7-9d0ac3a3fcf3", // Leonardo Phoenix 1.0
    width: 1024,
    height: 1024,
    num_images: 1,
    ultra: true,
    enhancePrompt: true,
    // Apply custom LoRAs via an `elements` array
    elements: [
      { akId: "your-lora-id", weight: 0.8 }
    ]
  })
});

const { sdGenerationJob } = await response.json();
const generationId = sdGenerationJob.generationId;

2. Poll for Status

Renders typically take 10–30 seconds. Poll every 5 seconds.

// GET /v1/generations/{id}
const poll = async (id) => {
  const res = await fetch(`https://cloud.leonardo.ai/api/rest/v1/generations/${id}`, {
    headers: { "Authorization": `Bearer ${API_KEY}` }
  });
  const { generations_by_pk } = await res.json();
  return generations_by_pk.generated_images; // Returns array when done
};

Prompting for Leonardo

Leonardo rewards specific descriptors but can become "overbaked" if the prompt is too long.

• Structure: Subject, Environment, Lighting, Style/Camera, Artist Influence (Optional)
• Ultra Pipeline: When ultra: true is set, you don't need to add "hyper-realistic" or "4k" — the pipeline handles the quality enhancement.
• Negative Prompts: Use them to remove common artifacts like extra limbs, blurry, text, watermark.

Credit Management

• Ultra features cost more — Warn the user if they are on a tight credit budget.
• Higher resolutions cost more — 1024x1024 is the standard; moving to 1536+ can triple the cost.
• Batches are efficient — Generating 4 images at once is often cheaper than 1+1+1+1.

Best Practices

1. Check for existing models: Always use the specific modelId for the look the user wants (Lucid for artistic, Phoenix for general/fast/character consistency via Phoenix 2.0, FLUX for text/realism).
2. Use Custom Elements: Use the elements array to bring in custom LoRAs and styles directly into your API call.
3. Use Guidance Scale: Keep it between 7 and 10 for most prompts. Too high and the image "burns"; too low and it ignores the prompt.
4. Show Progress: When used in an agent, tell the user "I've started the Leonardo generation (Task ID: ...), polling now."