API Reference

Generations

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create a generation

client.Generations.New(ctx, body) (*Generation, error)

POST/generations

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

ParametersExpand Collapse

body GenerationNewParams

Prompt param.Field[string]

Text prompt

minLength1

maxLength6000

AspectRatio param.Field[GenerationNewParamsAspectRatio]optional

Output aspect ratio. Valid values depend on the selected model and generation type; the server validates the final model-specific set.

const GenerationNewParamsAspectRatio3_1 GenerationNewParamsAspectRatio = "3:1"

const GenerationNewParamsAspectRatio2_1 GenerationNewParamsAspectRatio = "2:1"

const GenerationNewParamsAspectRatio21_9 GenerationNewParamsAspectRatio = "21:9"

const GenerationNewParamsAspectRatio16_9 GenerationNewParamsAspectRatio = "16:9"

const GenerationNewParamsAspectRatio4_3 GenerationNewParamsAspectRatio = "4:3"

const GenerationNewParamsAspectRatio3_2 GenerationNewParamsAspectRatio = "3:2"

const GenerationNewParamsAspectRatio1_1 GenerationNewParamsAspectRatio = "1:1"

const GenerationNewParamsAspectRatio3_4 GenerationNewParamsAspectRatio = "3:4"

const GenerationNewParamsAspectRatio2_3 GenerationNewParamsAspectRatio = "2:3"

const GenerationNewParamsAspectRatio9_16 GenerationNewParamsAspectRatio = "9:16"

const GenerationNewParamsAspectRatio1_2 GenerationNewParamsAspectRatio = "1:2"

const GenerationNewParamsAspectRatio1_3 GenerationNewParamsAspectRatio = "1:3"

ImageRef param.Field[[]ImageRef]optional

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

Data stringoptional

Base64-encoded image or video data

GenerationID stringoptional

UUID of a prior generation owned by the same caller. Used on source for image_edit, video_edit, and video_reframe chaining and on video.start_frame / video.end_frame for video extension.

formatuuid

MediaType stringoptional

MIME type (for example, image/jpeg or video/mp4). Required with data. Required with source.url on video_edit/video_reframe so the route can dispatch video ingest before fetching bytes; optional for image URLs.

URL stringoptional

Publicly accessible image URL, or a video URL when used as source for video_edit/video_reframe with media_type=video/*.

Model param.Field[Model]optional

Model identifier. uni-1 is the default image tier; uni-1-max produces higher-quality output than uni-1 at a higher per-image price. ray-3.2 is the public video model for text-to-video, image-to-video, and video-to-video editing.

OutputFormat param.Field[GenerationNewParamsOutputFormat]optional

Output image format

const GenerationNewParamsOutputFormatPng GenerationNewParamsOutputFormat = "png"

const GenerationNewParamsOutputFormatJpeg GenerationNewParamsOutputFormat = "jpeg"

Source param.Field[ImageRef]optional

Media reference for guided generation. Provide exactly one of url, inline base64 data, or generation_id. URL/data references accept image media at image positions; video_edit and video_reframe sources also accept source.url or source.data when source.media_type is a video/* MIME. generation_id chains image_edit off a prior image output, video_edit/video_reframe off a prior video output, and video.start_frame/end_frame for extension.

Style param.Field[GenerationNewParamsStyle]optional

Style preset (auto, manga)

const GenerationNewParamsStyleAuto GenerationNewParamsStyle = "auto"

const GenerationNewParamsStyleManga GenerationNewParamsStyle = "manga"

Type param.Field[GenerationNewParamsType]optional

The kind of generation to perform

const GenerationNewParamsTypeImage GenerationNewParamsType = "image"

const GenerationNewParamsTypeImageEdit GenerationNewParamsType = "image_edit"

const GenerationNewParamsTypeVideo GenerationNewParamsType = "video"

const GenerationNewParamsTypeVideoEdit GenerationNewParamsType = "video_edit"

const GenerationNewParamsTypeVideoReframe GenerationNewParamsType = "video_reframe"

UserID param.Field[string]optional

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

Video param.Field[VideoOptions]optional

Ray 3.2 video request options. Common output settings live at the top level for type=video, type=video_edit, and type=video_reframe; video-to-video conditioning lives under edit.

WebSearch param.Field[bool]optional

Enable web search grounding — the agent can search the web and download reference images before generating.

ReturnsExpand Collapse

type Generation struct{…}

Generation status and output

ID string

Generation identifier

formatuuid

CreatedAt string

Creation timestamp

Model Model

Model used

One of the following:

const ModelUni1 Model = "uni-1"

const ModelUni1Max Model = "uni-1-max"

const ModelRay3_2 Model = "ray-3.2"

State GenerationState

Current state of the generation

One of the following:

const GenerationStateQueued GenerationState = "queued"

const GenerationStateProcessing GenerationState = "processing"

const GenerationStateCompleted GenerationState = "completed"

const GenerationStateFailed GenerationState = "failed"

Type GenerationType

The kind of generation to perform

One of the following:

const GenerationTypeImage GenerationType = "image"

const GenerationTypeImageEdit GenerationType = "image_edit"

const GenerationTypeVideo GenerationType = "video"

const GenerationTypeVideoEdit GenerationType = "video_edit"

const GenerationTypeVideoReframe GenerationType = "video_reframe"

FailureCode GenerationFailureCodeoptional

Machine-readable failure code for programmatic handling

One of the following:

const GenerationFailureCodeContentModerated GenerationFailureCode = "content_moderated"

const GenerationFailureCodeGenerationFailed GenerationFailureCode = "generation_failed"

const GenerationFailureCodeBudgetExhausted GenerationFailureCode = "budget_exhausted"

const GenerationFailureCodeOutputNotFound GenerationFailureCode = "output_not_found"

const GenerationFailureCodeImageTooLarge GenerationFailureCode = "image_too_large"

const GenerationFailureCodeUnsupportedFormat GenerationFailureCode = "unsupported_format"

const GenerationFailureCodeCorruptInput GenerationFailureCode = "corrupt_input"

const GenerationFailureCodeInvalidRequest GenerationFailureCode = "invalid_request"

const GenerationFailureCodeRateLimited GenerationFailureCode = "rate_limited"

FailureReason stringoptional

Human-readable failure description

Output []GenerationOutputoptional

Generated outputs (populated on completion)

Type string

Media type (e.g. image, video)

URL string

Presigned URL (1hr expiry)

formaturi

Create a generation

Go

HTTP

TypeScript

Python

Go

CLI Tool

package main

import (
  "context"
  "fmt"

  "github.com/lumalabs/luma-agents-go"
  "github.com/lumalabs/luma-agents-go/option"
)

func main() {
  client := lumaagents.NewClient(
    option.WithAuthToken("My Auth Token"),
  )
  generation, err := client.Generations.New(context.TODO(), lumaagents.GenerationNewParams{
    Prompt: lumaagents.F("A glass of iced coffee on a marble countertop, morning light streaming through a window"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", generation.ID)
}

200 example

{
  "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

200 example

{
  "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"
    }
  ]
}