Skip to content
Luma Agents
lumalabs.ai
API Reference
Generations

Create a generation

generations.create(GenerationCreateParams**kwargs) -> Generation
POST/generations

Submit an image generation or edit job. Returns immediately with an opaque job ID to poll via GET /generations/{id}.

ParametersExpand Collapse
prompt: str

Text prompt

minLength1
maxLength6000
aspect_ratio: Optional[Literal["3:1", "2:1", "16:9", 6 more]]

Output aspect ratio

One of the following:
"3:1"
"2:1"
"16:9"
"3:2"
"1:1"
"2:3"
"9:16"
"1:2"
"1:3"
image_ref: Optional[Iterable[ImageRef]]

Reference images for style/content guidance. Up to 9 for type 'image', up to 8 for type 'image_edit'.

data: Optional[str]

Base64-encoded image data

media_type: Optional[str]

MIME type (e.g. image/jpeg). Required with data.

url: Optional[str]

Publicly accessible image URL

model: Optional[Model]

Model identifier. uni-1 is the default tier; uni-1-max produces higher-quality output than uni-1 at a higher per-image price. Both models are available to all accounts — see Pricing for per-image rates.

One of the following:
"uni-1"
"uni-1-max"
output_format: Optional[Literal["png", "jpeg"]]

Output image format

One of the following:
"png"
"jpeg"
source: Optional[Source]

Reference image for guided generation. Provide either url or inline base64 data (not both).

data: Optional[str]

Base64-encoded image data

media_type: Optional[str]

MIME type (e.g. image/jpeg). Required with data.

url: Optional[str]

Publicly accessible image URL

style: Optional[Literal["auto", "manga"]]

Style preset (auto, manga)

One of the following:
"auto"
"manga"
type: Optional[Literal["image", "image_edit"]]

The kind of generation to perform

One of the following:
"image"
"image_edit"
user_id: Optional[str]

Your end-user's stable opaque identifier (no PII). Forwarded to upstream model providers as their per-user tagging field so trust & safety violations can be attributed to a specific end-user rather than the whole API account. Also used for per-end-user usage breakdowns in /v1/usage. Strongly recommended for partner integrations.

maxLength256
ReturnsExpand Collapse
class Generation: …

Generation status and output

id: str

Generation identifier

formatuuid
created_at: str

Creation timestamp

model: Model

Model used

One of the following:
"uni-1"
"uni-1-max"
state: Literal["queued", "processing", "completed", "failed"]

Current state of the generation

One of the following:
"queued"
"processing"
"completed"
"failed"
type: Literal["image", "image_edit"]

The kind of generation to perform

One of the following:
"image"
"image_edit"
failure_code: Optional[GenerationFailureCode]

Machine-readable failure code for programmatic handling

One of the following:
"content_moderated"
"generation_failed"
"budget_exhausted"
"output_not_found"
"image_too_large"
"unsupported_format"
"corrupt_input"
"invalid_request"
"rate_limited"
failure_reason: Optional[str]

Human-readable failure description

output: Optional[List[GenerationOutput]]

Generated outputs (populated on completion)

type: str

Media type (e.g. image)

url: str

Presigned URL (1hr expiry)

formaturi

Create a generation

import os
from luma_agents import Luma

client = Luma(
    auth_token=os.environ.get("LUMA_AGENTS_API_KEY"),  # This is the default and can be omitted
)
generation = client.generations.create(
    prompt="A glass of iced coffee on a marble countertop, morning light streaming through a window",
)
print(generation.id)
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "created_at",
  "model": "uni-1",
  "state": "queued",
  "type": "image",
  "failure_code": "content_moderated",
  "failure_reason": "failure_reason",
  "output": [
    {
      "type": "type",
      "url": "https://example.com"
    }
  ]
}
Returns Examples
{
  "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "created_at": "created_at",
  "model": "uni-1",
  "state": "queued",
  "type": "image",
  "failure_code": "content_moderated",
  "failure_reason": "failure_reason",
  "output": [
    {
      "type": "type",
      "url": "https://example.com"
    }
  ]
}