# Generations ## Create a generation `client.generations.create(GenerationCreateParamsbody, RequestOptionsoptions?): Generation` **post** `/generations` Submit an image generation or edit job. Returns immediately with an opaque job ID to poll via GET /generations/{id}. ### Parameters - `body: GenerationCreateParams` - `prompt: string` Text prompt - `aspect_ratio?: "3:1" | "2:1" | "16:9" | 6 more | null` Output aspect ratio - `"3:1"` - `"2:1"` - `"16:9"` - `"3:2"` - `"1:1"` - `"2:3"` - `"9:16"` - `"1:2"` - `"1:3"` - `image_ref?: Array` Reference images for style/content guidance. Up to 9 for type 'image', up to 8 for type 'image_edit'. - `data?: string | null` Base64-encoded image data - `media_type?: string | null` MIME type (e.g. image/jpeg). Required with data. - `url?: string | null` Publicly accessible image URL - `model?: 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. - `"uni-1"` - `"uni-1-max"` - `output_format?: "png" | "jpeg" | null` Output image format - `"png"` - `"jpeg"` - `source?: Source | null` Reference image for guided generation. Provide either url or inline base64 data (not both). - `data?: string | null` Base64-encoded image data - `media_type?: string | null` MIME type (e.g. image/jpeg). Required with data. - `url?: string | null` Publicly accessible image URL - `style?: "auto" | "manga"` Style preset (auto, manga) - `"auto"` - `"manga"` - `type?: "image" | "image_edit"` The kind of generation to perform - `"image"` - `"image_edit"` - `user_id?: string | null` 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. - `web_search?: boolean` Enable web search grounding — the agent can search the web and download reference images before generating. ### Returns - `Generation` Generation status and output - `id: string` Generation identifier - `created_at: string` Creation timestamp - `model: Model` Model used - `"uni-1"` - `"uni-1-max"` - `state: "queued" | "processing" | "completed" | "failed"` Current state of the generation - `"queued"` - `"processing"` - `"completed"` - `"failed"` - `type: "image" | "image_edit"` The kind of generation to perform - `"image"` - `"image_edit"` - `failure_code?: GenerationFailureCode | null` Machine-readable failure code for programmatic handling - `"content_moderated"` - `"generation_failed"` - `"budget_exhausted"` - `"output_not_found"` - `"image_too_large"` - `"unsupported_format"` - `"corrupt_input"` - `"invalid_request"` - `"rate_limited"` - `failure_reason?: string | null` Human-readable failure description - `output?: Array` Generated outputs (populated on completion) - `type: string` Media type (e.g. image) - `url: string` Presigned URL (1hr expiry) ### Example ```typescript import Luma from 'luma-agents'; const client = new Luma({ authToken: process.env['LUMA_AGENTS_API_KEY'], // This is the default and can be omitted }); const generation = await client.generations.create({ prompt: 'A glass of iced coffee on a marble countertop, morning light streaming through a window', }); console.log(generation.id); ``` #### Response ```json { "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" } ] } ``` ## Get a generation `client.generations.get(stringgenerationID, RequestOptionsoptions?): Generation` **get** `/generations/{generation_id}` Poll for generation status and output. On completion, the response includes presigned URLs to download the generated images. ### Parameters - `generationID: string` ### Returns - `Generation` Generation status and output - `id: string` Generation identifier - `created_at: string` Creation timestamp - `model: Model` Model used - `"uni-1"` - `"uni-1-max"` - `state: "queued" | "processing" | "completed" | "failed"` Current state of the generation - `"queued"` - `"processing"` - `"completed"` - `"failed"` - `type: "image" | "image_edit"` The kind of generation to perform - `"image"` - `"image_edit"` - `failure_code?: GenerationFailureCode | null` Machine-readable failure code for programmatic handling - `"content_moderated"` - `"generation_failed"` - `"budget_exhausted"` - `"output_not_found"` - `"image_too_large"` - `"unsupported_format"` - `"corrupt_input"` - `"invalid_request"` - `"rate_limited"` - `failure_reason?: string | null` Human-readable failure description - `output?: Array` Generated outputs (populated on completion) - `type: string` Media type (e.g. image) - `url: string` Presigned URL (1hr expiry) ### Example ```typescript import Luma from 'luma-agents'; const client = new Luma({ authToken: process.env['LUMA_AGENTS_API_KEY'], // This is the default and can be omitted }); const generation = await client.generations.get('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e'); console.log(generation.id); ``` #### Response ```json { "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" } ] } ``` ## Domain Types ### Generation - `Generation` Generation status and output - `id: string` Generation identifier - `created_at: string` Creation timestamp - `model: Model` Model used - `"uni-1"` - `"uni-1-max"` - `state: "queued" | "processing" | "completed" | "failed"` Current state of the generation - `"queued"` - `"processing"` - `"completed"` - `"failed"` - `type: "image" | "image_edit"` The kind of generation to perform - `"image"` - `"image_edit"` - `failure_code?: GenerationFailureCode | null` Machine-readable failure code for programmatic handling - `"content_moderated"` - `"generation_failed"` - `"budget_exhausted"` - `"output_not_found"` - `"image_too_large"` - `"unsupported_format"` - `"corrupt_input"` - `"invalid_request"` - `"rate_limited"` - `failure_reason?: string | null` Human-readable failure description - `output?: Array` Generated outputs (populated on completion) - `type: string` Media type (e.g. image) - `url: string` Presigned URL (1hr expiry) ### Generation Failure Code - `GenerationFailureCode = "content_moderated" | "generation_failed" | "budget_exhausted" | 6 more` Machine-readable failure code for programmatic handling - `"content_moderated"` - `"generation_failed"` - `"budget_exhausted"` - `"output_not_found"` - `"image_too_large"` - `"unsupported_format"` - `"corrupt_input"` - `"invalid_request"` - `"rate_limited"` ### Generation Output - `GenerationOutput` A single generated output - `type: string` Media type (e.g. image) - `url: string` Presigned URL (1hr expiry) ### Model - `Model = "uni-1" | "uni-1-max"` 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. - `"uni-1"` - `"uni-1-max"`