API Reference

Image Generation API

A fast REST endpoint that returns hosted image URLs. Authenticate with an API key for a 1000 images/day quota. Batch 1–6 renders per request, tune inference steps 1–15, and toggle safety filtering.

Speed

Turbo

Batch

1–6

Auth

Required

Safety

Optional

Insert my API key into examples

Turn on to replace idai_your_key_here with a real key from your account.

Off

Base URL

text

https://imaginedrawai.lovable.app/api/v1/images

Send POST requests with a JSON body to the endpoint above. Add Authorization: Bearer <key> to authenticate — create keys in Profile → API access.

Quick Test URL (GET)

Paste this into your browser to generate an image directly. The URL carries the API key and prompt as query params. Without a valid apikey the request fails with 401.

text

https://imaginedrawai.lovable.app/api/v1/images?apikey=idai_your_key_here&prompt=a+red+panda+in+a+forest

Optional params: image, dimensions, steps, safety. Example: &dimensions=16:9&image=2.

Request Parameters

Name	Type	Required	Default	Description
prompt	string	Yes	—	Text description of the image
image	integer	No	1	Number of images (1–6)
dimensions	string	No	1:1	Aspect ratio key (see below)
safety	boolean	No	false	Enable safety filtering
steps	integer	No	4	Inference steps (1–15)

Available Dimensions

Key	Aspect	Resolution	Note
1:1	Square	1024×1024	Perfect square
1:2	Portrait	512×1024	Tall portrait
3:2	Landscape	768×512	Classic photo
3:4	Portrait	768×1024	Standard portrait
16:9	Widescreen	1024×576	Widescreen
9:16	Mobile	576×1024	Mobile / story

Integration Examples

cURL

bash

# Authenticate with your API key (1000 images/day/key)
curl -X POST 'https://imaginedrawai.lovable.app/api/v1/images' \
  -H 'Authorization: Bearer idai_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "beautiful sunset over mountains",
    "image": 2,
    "dimensions": "16:9",
    "safety": true,
    "steps": 8
  }'

JavaScript (fetch)

javascript

// Node.js / Browser fetch
async function generate(prompt, apiKey) {
  const res = await fetch("https://imaginedrawai.lovable.app/api/v1/images", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${apiKey}`, // required
    },
    body: JSON.stringify({
      prompt,
      image: 2,
      dimensions: "16:9",
      safety: true,
      steps: 8,
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  const data = await res.json();
  return data.images; // string[] of image URLs
}

const urls = await generate(
  "A cinematic photo of a red panda",
  "idai_your_key_here", // create one in Profile → API access
);
console.log(urls);

Python (requests)

python

# pip install requests
import requests

def generate(prompt: str, api_key: str):
    r = requests.post(
        "https://imaginedrawai.lovable.app/api/v1/images",
        headers={"Authorization": f"Bearer {api_key}"},
        json={
            "prompt": prompt,
            "image": 2,
            "dimensions": "16:9",
            "safety": True,
            "steps": 8,
        },
        timeout=60,
    )
    r.raise_for_status()
    return r.json()["images"]

urls = generate(
    "A cinematic photo of a red panda",
    api_key="idai_your_key_here",  # required
)
print(urls)

React component

tsx

import { useState } from "react";

const API_KEY = "idai_your_key_here"; // required

export function ImageGenerator() {
  const [prompt, setPrompt] = useState("");
  const [images, setImages] = useState<string[]>([]);
  const [loading, setLoading] = useState(false);

  async function run() {
    setLoading(true);
    try {
      const res = await fetch("https://imaginedrawai.lovable.app/api/v1/images", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${API_KEY}`,
        },
        body: JSON.stringify({
          prompt,
          image: 2,
          dimensions: "1:1",
          safety: false,
          steps: 4,
        }),
      });
      const data = await res.json();
      setImages(data.images ?? []);
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <input value={prompt} onChange={(e) => setPrompt(e.target.value)} />
      <button onClick={run} disabled={loading}>
        {loading ? "Generating…" : "Generate"}
      </button>
      <div>
        {images.map((src) => (
          <img key={src} src={src} alt="" />
        ))}
      </div>
    </div>
  );
}

Response Format

A successful response returns a JSON object with an images array of hosted image URLs.

json

{
  "images": [
    "https://…/image-1.png",
    "https://…/image-2.png"
  ],
  "dimensions": "16:9"
}

Errors

Errors return a non-200 status with a JSON error string.

json

// 400 — validation
{ "error": "Prompt is required" }

// 401 — API key rejected
{ "error": "Invalid API key" }
{ "error": "API key revoked" }
{ "error": "API key expired" }

// 502 — upstream failure
{ "error": "Upstream error" }

400 — Missing or invalid parameters. Verify prompt, image, and dimensions.
429 — Rate limited. Back off and retry.
5xx — Upstream issue. Retry with exponential backoff.

Ready to build

Try it live in the Imagine Draw studio

Open Studio