Image generation

Create images from text descriptions. This guide covers every parameter for type: "image" requests. For editing existing images, see Image editing.

Basic request

At minimum, you need a prompt:

Python

from luma_agents import Luma

client = Luma()

generation = client.generations.create(
    prompt="An astronaut riding a horse on Mars, oil painting style",
)

TypeScript

import Luma from "luma-agents";

const client = new Luma();

const generation = await client.generations.create({
  prompt: "An astronaut riding a horse on Mars, oil painting style",
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Prompt: lumaagents.F("An astronaut riding a horse on Mars, oil painting style"),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "An astronaut riding a horse on Mars, oil painting style"}'

CLI

luma-agents-cli generations create \
  --prompt "An astronaut riding a horse on Mars, oil painting style"

When no other parameters are specified, the API uses these defaults: model: "uni-1", type: "image", style: "auto". aspect_ratio and output_format are left unset so the model can pick an appropriate value based on the prompt — pass them explicitly to force a specific ratio or format.

Parameters

prompt (required)

A text description of the image to generate, from 1 to 6,000 characters. Be specific about subject, setting, lighting, style, and mood for best results.

{
  "prompt": "A neon-lit Tokyo alley in the rain, reflections on wet pavement, cinematic photography"
}

model

Which model to use. Defaults to "uni-1". Supported values:

• uni-1 — the default.
• uni-1-max — produces higher-quality output than uni-1. See Models for details and Pricing for per-image rates.

{
  "model": "uni-1"
}

aspect_ratio

Controls the output image dimensions. When omitted (or null), the model selects an appropriate ratio based on the prompt. Pass one of the supported values below to force a specific ratio.

Value	Orientation
3:1	Ultra-wide landscape
2:1	Wide landscape
16:9	Standard widescreen
3:2	Classic landscape
1:1	Square
2:3	Classic portrait
9:16	Standard portrait
1:2	Tall portrait
1:3	Ultra-tall portrait

Some style presets restrict the allowed aspect_ratio set. In particular, style: "manga" only permits portrait ratios (2:3, 9:16, 1:2, 1:3); pairing it with a landscape or square ratio is rejected with HTTP 422. See style below for the full contract.

Python

generation = client.generations.create(
    prompt="A white cat wearing a tiny crown, sitting on a stack of old books",
    aspect_ratio="1:1",
)

TypeScript

const generation = await client.generations.create({
  prompt: "A white cat wearing a tiny crown, sitting on a stack of old books",
  aspect_ratio: "1:1",
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Prompt:      lumaagents.F("A white cat wearing a tiny crown, sitting on a stack of old books"),
    AspectRatio: lumaagents.F(lumaagents.GenerationNewParamsAspectRatio1_1),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A white cat wearing a tiny crown, sitting on a stack of old books",
    "aspect_ratio": "1:1"
  }'

style

Applies a style preset to the generation. Defaults to "auto".

Value	Description	Allowed aspect_ratio
auto	Model selects the best style for the prompt	All 9 values, or omit to let the model pick
manga	Manga/anime aesthetic with ink outlines and screentone shading	Portrait only: 2:3, 9:16, 1:2, 1:3 (or omit)

Python

generation = client.generations.create(
    prompt="A warrior standing at the edge of a cliff overlooking a vast ocean",
    style="manga",
    aspect_ratio="2:3",
)

TypeScript

const generation = await client.generations.create({
  prompt: "A warrior standing at the edge of a cliff overlooking a vast ocean",
  style: "manga",
  aspect_ratio: "2:3",
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Prompt:      lumaagents.F("A warrior standing at the edge of a cliff overlooking a vast ocean"),
    Style:       lumaagents.F(lumaagents.GenerationNewParamsStyleManga),
    AspectRatio: lumaagents.F(lumaagents.GenerationNewParamsAspectRatio2_3),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A warrior standing at the edge of a cliff overlooking a vast ocean",
    "style": "manga",
    "aspect_ratio": "2:3"
  }'

The manga style works best with action scenes, character portraits, and dramatic compositions. For subtle anime-inspired aesthetics, describe the style in your prompt instead — e.g., “anime-inspired illustration with soft pastel colors”.

style: "manga" aspect-ratio constraint

manga is portrait-only. Pair it with a portrait aspect_ratio (2:3, 9:16, 1:2, 1:3), or omit aspect_ratio to let the model pick one. Pairing style: "manga" with a landscape or square ratio (3:1, 2:1, 16:9, 3:2, 1:1) is rejected at submit time with HTTP 422:

{
  "detail": "aspect_ratio='1:1' is not allowed when style='manga'. Valid aspect_ratio: 1:2, 1:3, 2:3, 9:16"
}

The Valid aspect_ratio: list always names the portrait values you can use. Branch on the 422 status code; the detail string format is stable but parse it loosely (the leading aspect_ratio=... value reflects what you sent).

This constraint applies to type: "image" only. On type: "image_edit" requests, the output dimensions are derived from the source image rather than the body, so style: "manga" is accepted regardless of source aspect ratio — see Image editing.

output_format

Sets the output image format. When omitted (or null), the model selects an appropriate format based on the prompt. Pass an explicit value to force a specific format.

Value	Best for
png	Lossless quality
jpeg	Smaller file size, photographs

web_search

When set to true, the model searches the web for visual references before generating. This improves accuracy for prompts that reference real-world subjects, landmarks, or products.

Python

generation = client.generations.create(
    prompt="The Eiffel Tower at golden hour with cherry blossoms in the foreground",
    web_search=True,
)

TypeScript

const generation = await client.generations.create({
  prompt: "The Eiffel Tower at golden hour with cherry blossoms in the foreground",
  web_search: true,
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Prompt:    lumaagents.F("The Eiffel Tower at golden hour with cherry blossoms in the foreground"),
    WebSearch: lumaagents.F(true),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The Eiffel Tower at golden hour with cherry blossoms in the foreground",
    "web_search": true
  }'

Web search adds a few seconds to generation time but dramatically improves accuracy for prompts that reference specific real-world subjects.

image_ref

Provide up to 9 reference images to guide the generation. Each reference accepts either a url (publicly accessible) or inline data (base64-encoded with media_type) — not both.

image_ref is not image editing. With type: "image" + image_ref, the references are style/content guidance for a brand-new image — none of the input pixels are preserved. If you want to modify an existing image and keep its content, use type: "image_edit" with a source instead. See When to use image editing for the full distinction.

Single reference image:

Python

generation = client.generations.create(
    prompt="A similar scene but at sunset, with warm orange and pink tones",
    image_ref=[
        {"url": "https://example.com/reference.jpg"},
    ],
)

TypeScript

const generation = await client.generations.create({
  prompt: "A similar scene but at sunset, with warm orange and pink tones",
  image_ref: [
    { url: "https://example.com/reference.jpg" },
  ],
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Prompt: lumaagents.F("A similar scene but at sunset, with warm orange and pink tones"),
    ImageRef: lumaagents.F([]lumaagents.ImageRefParam{
        {URL: lumaagents.F("https://example.com/reference.jpg")},
    }),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A similar scene but at sunset, with warm orange and pink tones",
    "image_ref": [
      {"url": "https://example.com/reference.jpg"}
    ]
  }'

Multiple references — combine different visual aspects:

Python

generation = client.generations.create(
    prompt="Use the color palette from the first reference and the composition from the second. "
           "Create a portrait of a jazz musician in a smoky club.",
    image_ref=[
        {"url": "https://example.com/color-reference.jpg"},
        {"url": "https://example.com/composition-reference.jpg"},
    ],
)

TypeScript

const generation = await client.generations.create({
  prompt:
    "Use the color palette from the first reference and the composition from the second. " +
    "Create a portrait of a jazz musician in a smoky club.",
  image_ref: [
    { url: "https://example.com/color-reference.jpg" },
    { url: "https://example.com/composition-reference.jpg" },
  ],
});

Go

generation, err := client.Generations.New(ctx, lumaagents.GenerationNewParams{
    Prompt: lumaagents.F(
        "Use the color palette from the first reference and the composition from the second. " +
        "Create a portrait of a jazz musician in a smoky club.",
    ),
    ImageRef: lumaagents.F([]lumaagents.ImageRefParam{
        {URL: lumaagents.F("https://example.com/color-reference.jpg")},
        {URL: lumaagents.F("https://example.com/composition-reference.jpg")},
    }),
})

cURL

curl -X POST https://agents.lumalabs.ai/v1/generations \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Use the color palette from the first reference and the composition from the second. Create a portrait of a jazz musician in a smoky club.",
    "image_ref": [
      {"url": "https://example.com/color-reference.jpg"},
      {"url": "https://example.com/composition-reference.jpg"}
    ]
  }'

Using base64 data instead of a URL:

{
  "prompt": "Reimagine this in watercolor style",
  "image_ref": [
    {
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
      "media_type": "image/png"
    }
  ]
}

Each image_ref entry must provide either url or data — not both. URLs must be publicly accessible. Base64 images must include media_type. Maximum 50 MB per image, up to 9 references total.

Use inline data only for small media files. For anything larger, pass a hosted url instead of inlining.

When using multiple references, explicitly label each image’s role in the prompt: “Use the first reference for the color palette” and “Use the second for the composition.” Without labels, the model guesses which aspects to pull from each reference.

Validation rules

Rule	Constraint
prompt	Required. 1–6,000 characters
model	Must be one of: uni-1, uni-1-max. Defaults to uni-1
type	Must be image or image_edit. Defaults to image
aspect_ratio	Must be one of the 9 supported values, or null (default — model picks)
style	Must be auto or manga. Defaults to auto
style + aspect_ratio	When style="manga" (and type="image"), aspect_ratio must be portrait — 2:3, 9:16, 1:2, 1:3, or omitted. Other values return HTTP 422
output_format	Must be png or jpeg, or null (default — model picks)
image_ref	Maximum 9 entries. Each must provide url or data — not both
image_ref[].data	Must be valid base64. Requires media_type. Max 50 MB, max 8000 px per side
image_ref[].url	Must be publicly accessible. Max 50 MB, max 8000 px per side
web_search	Must be a boolean. Defaults to false
source	Must be null or omitted for type: "image". See Image editing

When aspect_ratio or output_format is set to null, the model selects an appropriate value based on the prompt.

See Error handling for the full list of validation errors.

Response

A successful request returns HTTP 201 with a GenerationResponse:

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "type": "image",
  "state": "queued",
  "model": "uni-1",
  "created_at": "2026-04-08T12:00:00Z",
  "output": [],
  "failure_reason": null,
  "failure_code": null
}

Generation states

State	Description
queued	Job is waiting to be picked up
processing	Image is being generated
completed	Generation succeeded — output contains download URLs
failed	Generation failed — check failure_reason and failure_code

Poll GET /v1/generations/{id} until the state reaches completed or failed. See the Quickstart for polling examples.

Output URLs

On completion, output contains one or more objects with presigned download URLs:

{
  "output": [
    {
      "type": "image",
      "url": "https://storage.example.com/generations/d290f1ee/output.png?X-Amz-Expires=3600&..."
    }
  ]
}

Presigned URLs expire after 1 hour. Download images promptly or generate new URLs by polling the endpoint again.

Next steps

• Image editing — Modify existing images with text prompts and reference images
• Video generation — Ray 3.2 text-to-video and image-to-video
• Video editing — Ray 3.2 video editing
• Models — Model capabilities and limitations
• Pricing — Pay-as-you-go and Provisioned Throughput plans
• Error handling — Every error code with troubleshooting steps
• FAQ — Quick answers to common questions
• API Reference — Complete endpoint specifications