Use Uni 1 with Comfy Router

Call luma_2/uni-1 through Comfy Router: endpoint, request shape and the response Router returns.

API Reference for luma_2/uni-1, served by Comfy Router from Luma 2.

Quick start

Create a key at platform.comfy.org/profile/api-keys and export it as COMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk, npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP.

Model ID: luma_2/uni-1

Endpoint: POST https://api.comfy.org/v2/models/luma_2/uni-1

Python

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment. Each call sends a fresh
# Idempotency-Key and waits up to 10 minutes for the finished result.
with Comfy() as client:
    result = client.models.run(
        "luma_2/uni-1",
        {
            "prompt": "a red circle on a plain white background",
            "type": "image",
        },
    )

print(result)

Schema

Input

aspect_ratio · string

Output aspect ratio. The ray-3.2 video models support the subset 9:16, 3:4, 1:1, 4:3, 16:9, 21:9.

Possible values: 3:1, 2:1, 21:9, 16:9, 3:2, 4:3, 1:1, 3:4, 2:3, 9:16, 1:2, 1:3

image_ref · object[]

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

image_ref[].data · string

Base64-encoded image or video data

image_ref[].generation_id · string

UUID of a prior completed generation to reuse as the source. Used by ray-3.2 video_edit / video_reframe.

image_ref[].media_type · string

MIME type. Required with data (and with url for video sources, e.g. video/mp4 on video_edit / video_reframe).

image_ref[].url · string

Publicly accessible image or video URL

model · string

Model to use. uni-1 / uni-1-max for image generation, ray-3.2 for video generation, editing, and reframing.

output_format · string

Output image format

Possible values: png, jpeg

prompt · string · required

Text prompt

source · object

Reference to an image or video. Used for style/content guidance, guided generation, video-edit/video-reframe sources, and guide keyframes. Provide exactly one of generation_id, url, or data.

source.data · string

Base64-encoded image or video data

source.generation_id · string

UUID of a prior completed generation to reuse as the source. Used by ray-3.2 video_edit / video_reframe.

source.media_type · string

MIME type. Required with data (and with url for video sources, e.g. video/mp4 on video_edit / video_reframe).

source.url · string

Publicly accessible image or video URL

style · string

Style preset

Possible values: auto, manga

type · string

The kind of generation to perform. image/image_edit are produced by the uni-1 / uni-1-max models; video/video_edit/video_reframe are produced by the ray-3.2 model.

Possible values: image, image_edit, video, video_edit, video_reframe

video · object

Video output settings for ray-3.2. Only the fields that affect validation and billing are modelled here; additional fields (edit controls, end_frame, loop, source_position) are forwarded to Luma untouched.

video.duration · string

Clip duration for ray-3.2 video / video_edit. Defaults to 5s. HDR generation (type video) is restricted to 5s.

Possible values: 5s, 10s

video.exr_export · boolean

Export an EXR file alongside the MP4. Requires hdr true. Rejected for video_reframe.

video.hdr · boolean

Render in HDR. Requires 720p/1080p. Rejected for video_reframe.

video.keyframes · object[]

Guide-frame images. A single keyframe makes a type “video” request a single-keyframe extend, which always bills as one 5s block.

video.keyframes[].data · string

Base64-encoded image or video data

video.keyframes[].generation_id · string

UUID of a prior completed generation to reuse as the source. Used by ray-3.2 video_edit / video_reframe.

video.keyframes[].media_type · string

MIME type. Required with data (and with url for video sources, e.g. video/mp4 on video_edit / video_reframe).

video.keyframes[].url · string

Publicly accessible image or video URL

video.loop · boolean

Loop the generated clip. Create-only (type video).

video.resolution · string

Output resolution for ray-3.2 video. Defaults to 720p. 360p is the draft tier. HDR requires 720p or 1080p.

Possible values: 360p, 540p, 720p, 1080p

video.start_frame · object

Reference to an image or video. Used for style/content guidance, guided generation, video-edit/video-reframe sources, and guide keyframes. Provide exactly one of generation_id, url, or data.

video.start_frame.data · string

Base64-encoded image or video data

video.start_frame.generation_id · string

UUID of a prior completed generation to reuse as the source. Used by ray-3.2 video_edit / video_reframe.

video.start_frame.media_type · string

MIME type. Required with data (and with url for video sources, e.g. video/mp4 on video_edit / video_reframe).

video.start_frame.url · string

Publicly accessible image or video URL

web_search · boolean

Enable web search grounding

Generated from the schema Router serves at GET /v2/models/luma_2/uni-1/openapi.json, the same document it validates a call against before the request reaches the provider.

Output

created_at · string

Creation timestamp

failure_code · string

Machine-readable failure code for programmatic handling

Possible values: content_moderated, generation_failed, budget_exhausted, output_not_found

failure_reason · string

Human-readable failure description, populated only on a FAILED generation. null on a successful one.

id · string

Generation identifier

model · string

Model used

output · object[]

A generated output entry

output[].type · string

Media type (e.g. image)

output[].url · string

Presigned URL (1hr expiry)

state · string

Current state of the generation

Possible values: queued, processing, completed, failed

type · string

The kind of generation to perform. image/image_edit are produced by the uni-1 / uni-1-max models; video/video_edit/video_reframe are produced by the ray-3.2 model.

Possible values: image, image_edit, video, video_edit, video_reframe

Examples

Input

{
  "prompt": "a red circle on a plain white background",
  "type": "image"
}

Output

{
  "created_at": "2027-01-01T00:00:00Z",
  "failure_code": null,
  "failure_reason": null,
  "id": "gen-luma-agents-3f2a7c1e8b40",
  "model": "uni-1",
  "output": [
    {
      "type": "image",
      "url": "https://example.invalid/luma_2/uni-1/generated.png"
    }
  ],
  "state": "completed",
  "type": "image"
}

Before you ship

The snippets above are the shortest working call. Three things are the same for every model and are documented once on the Comfy Router headers page: send an Idempotency-Key on every paid call and reuse it when you retry, expect the connection to be held up to Router’s 10 minute deadline, and keep X-Comfy-Request-Id from every response. The SDKs do all three for you; the cURL tab does none of them. On failure, X-Comfy-Error-Type names the bucket, and a 422 means the body failed the model’s schema and was never billed.

Headers

Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.

Quick Start

Typed error handling in Python and TypeScript, reading the 422, walking the catalog.

Limitations

What Router does not do today, and what to use instead.