Create Image

Creates an image given a prompt

For coding agents, discover the current recommended image shortlist first with GET /v1/models?recommended_for=image, then send the selected model explicitly to this endpoint.

Request Body

model · string · default: "dall-e-3"

Model to use (e.g., dall-e-3, flux-pro, midjourney).

prompt · string · required

Text description of the desired image.

n · integer · default: "1"

Number of images to generate (1-4, model dependent).

size · string · default: "1024x1024"

Image size. Options vary by model:

• DALL-E 3: 1024x1024, 1792x1024, 1024x1792
• Other models: 512x512, 1024x1024, etc.

quality · string · default: "standard"

Image quality (standard or hd). DALL-E 3 only.

response_format · string · default: "url"

Response format: url or b64_json.

style · string · default: "vivid"

Style for DALL-E 3: vivid or natural.

user · string

A unique identifier for the end-user.

Response

Inline Response

created · integer

Unix timestamp of creation.

data · array

Array of generated images.

Each object contains:

• url (string): URL of the generated image
• b64_json (string): Base64-encoded image (if requested)
• revised_prompt (string): The prompt used (DALL-E 3)

Async Task Response

Some image models return an async task immediately, and some may behave as either inline or task-based depending on the routed provider path. When the response includes status: "pending", treat it as an async task response:

Use the returned poll_url exactly when it is provided. Treat task_id as the async task identity for follow-up polling.

created · integer

Unix timestamp of creation.

task_id · string

Unique task identifier for polling.

status · string

Initial status: pending.

poll_url · string

Relative URL to poll for results (for example, /v1/images/generations/{task_id} or /v1/tasks/{task_id}).

data · array

Array with placeholder data. url will be empty until completed.

When you receive status: "pending", use the Get Image Status endpoint to poll for the result.

cURL

curl -X POST "https://api.lemondata.cc/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dall-e-3",
    "prompt": "A white cat sitting on a windowsill watching rain",
    "size": "1024x1024",
    "quality": "standard",
    "n": 1
  }'

Inline Response

{
  "created": 1706000000,
  "data": [
    {
      "url": "https://...",
      "revised_prompt": "A fluffy white cat with bright eyes sitting peacefully on a wooden windowsill, watching raindrops stream down the glass window..."
    }
  ]
}

Available Models

Model	Type	Features
dall-e-3	Usually inline	Best quality, prompt enhancement
dall-e-2	Usually inline	Faster, more affordable
flux-pro	Often task-based	Photorealistic, high quality
flux-schnell	Usually inline	Very fast
midjourney	Often task-based	Artistic style
ideogram-v3	Often task-based	Best text rendering
stable-diffusion-3	Usually inline	Open source, customizable

Do not hard-code a model as always synchronous or always asynchronous. If the create response returns status: "pending", follow poll_url and poll until completion.

Handling Task-Based Responses

For image models, always check whether the response contains status: "pending":

import requests
import time

def generate_image(prompt, model="midjourney"):
    # Create image request
    response = requests.post(
        "https://api.lemondata.cc/v1/images/generations",
        headers={"Authorization": "Bearer sk-your-api-key"},
        json={"model": model, "prompt": prompt}
    )
    data = response.json()

    # Check if task-based
    if data.get("status") == "pending":
        task_id = data["task_id"]
        poll_url = data.get("poll_url")
        print(f"Image task started: {task_id}")

        # Poll for result
        while True:
            status_resp = requests.get(
                f"https://api.lemondata.cc{poll_url}" if poll_url else f"https://api.lemondata.cc/v1/images/generations/{task_id}",
                headers={"Authorization": "Bearer sk-your-api-key"}
            )
            status_data = status_resp.json()

            if status_data["status"] == "completed":
                return status_data["data"][0]["url"]
            elif status_data["status"] == "failed":
                raise Exception(status_data.get("error", "Generation failed"))

            time.sleep(3)
    else:
        # Inline response
        return data["data"][0]["url"]

# Usage
url = generate_image("a beautiful sunset over mountains", model="midjourney")
print(f"Generated image: {url}")