Comfy Router で Uni 1 を使用する

Luma 2 から Comfy Router が提供する luma_2/uni-1 の API リファレンスです。

クイックスタート

あなたの Comfy ワークスペースでキーを作成し、COMFY_API_KEY としてエクスポートします。Python と TypeScript のスニペットは Comfy SDK（pip install comfy-sdk、npm install @comfyorg/sdk）を使用しています。cURL のスニペットは、同じ呼び出しを生の HTTP で実行します。 モデル ID: luma_2/uni-1 エンドポイント: POST https://api.comfy.org/v2/models/luma_2/uni-1

Wait for the result
Queue and collect later

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment.
# The SDK automatically creates an idempotency key and reuses it for automatic retries.
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)

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment.
// The SDK automatically creates an idempotency key and reuses it for automatic retries.
const { data } = await comfy.models.run("luma_2/uni-1", {
  prompt: "a red circle on a plain white background",
  type: "image",
});

console.log(data);

curl https://api.comfy.org/v2/models/luma_2/uni-1 \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"a red circle on a plain white background\", \"type\": \"image\"}"

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment.
# Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
with Comfy() as client:
    handle = client.models.submit(
        "luma_2/uni-1",
        {
            "prompt": "a red circle on a plain white background",
            "type": "image",
        },
    )
    print("request_id:", handle.request_id)  # with the model ID, all another process needs

    # Poll until the request completes, waiting the Retry-After the server names.
    for update in handle.iter_events():
        print(update.status, update.queue_position)

    # The provider's own payload, the same value models.run() returns.
    # A request that failed or was cancelled raises the typed Router error here.
    result = handle.get()

print(result)

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment.
// Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
const handle = await comfy.models.submit("luma_2/uni-1", {
  prompt: "a red circle on a plain white background",
  type: "image",
});
console.log("requestId:", handle.requestId); // with the model ID, all another process needs

// Poll until the request completes, waiting the Retry-After the server names.
for await (const update of handle.events()) {
  console.log(update.status, update.queuePosition);
}

// The same result models.run() returns. A request that failed or was cancelled rejects here.
const result = await handle.get();

console.log(result.data);

# 1. Submit. Router answers 201 with request_id, status_url, response_url and cancel_url.
curl https://api.comfy.org/v2/models/luma_2/uni-1/requests \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"a red circle on a plain white background\", \"type\": \"image\"}"

# 2. Poll until status is COMPLETED, waiting the Retry-After seconds each response names.
REQUEST_ID="<request_id from the 201 body>"
curl -i https://api.comfy.org/v2/models/luma_2/uni-1/requests/$REQUEST_ID/status \
  -H "X-API-Key: $COMFY_API_KEY"

# 3. Collect. 200 with the model's native output, 202 with the status body while it is still running.
curl https://api.comfy.org/v2/models/luma_2/uni-1/requests/$REQUEST_ID \
  -H "X-API-Key: $COMFY_API_KEY"

スキーマ

入力

string

出力アスペクト比。ray-3.2 ビデオモデルは 9:16、3:4、1:1、4:3、16:9、21:9 のサブセットをサポートします。指定可能な値: 3:1、2:1、21:9、16:9、3:2、4:3、1:1、3:4、2:3、9:16、1:2、1:3

object[]

スタイル／コンテンツのガイダンス用の参照画像。type ‘image’ では最大 9 枚、type ‘image_edit’ では最大 8 枚です。

string

Base64 エンコードされた画像またはビデオデータ

string

ソースとして再利用する、以前に完了した生成の UUID。ray-3.2 の video_edit / video_reframe で使用されます。

string

MIME タイプ。data と併用する場合に必須です（ビデオソースの場合は url と併用する場合も必須。例: video_edit / video_reframe での video/mp4）。

string

公開アクセス可能な画像またはビデオの URL

string

使用するモデル。画像生成には uni-1 / uni-1-max、ビデオの生成、編集、リフレーミングには ray-3.2。

string

出力画像フォーマット指定可能な値: png、jpeg

string

必須

テキストプロンプト

object

画像またはビデオへの参照。スタイル／コンテンツのガイダンス、ガイド付き生成、video-edit/video-reframe のソース、ガイドキーフレームに使用されます。generation_id、url、data のいずれか 1 つだけを指定してください。

string

Base64 エンコードされた画像またはビデオデータ

string

ソースとして再利用する、以前に完了した生成の UUID。ray-3.2 の video_edit / video_reframe で使用されます。

string

MIME タイプ。data と併用する場合に必須です（ビデオソースの場合は url と併用する場合も必須。例: video_edit / video_reframe での video/mp4）。

string

公開アクセス可能な画像またはビデオの URL

string

スタイルプリセット指定可能な値: auto、manga

string

実行する生成の種類。image/image_edit は uni-1 / uni-1-max モデルによって生成され、video/video_edit/video_reframe は ray-3.2 モデルによって生成されます。指定可能な値: image、image_edit、video、video_edit、video_reframe

object

ray-3.2 のビデオ出力設定。ここでは検証と課金に影響するフィールドのみをモデル化しています。追加のフィールド（編集コントロール、end_frame、loop、source_position）はそのまま Luma に転送されます。

string

ray-3.2 の video / video_edit のクリップ再生時間。デフォルトは 5s。HDR 生成（type video）は 5s に制限されています。指定可能な値: 5s、10s

boolean

MP4 と一緒に EXR ファイルをエクスポートします。hdr が true である必要があります。video_reframe では拒否されます。

boolean

HDR でレンダリングします。720p/1080p が必要です。video_reframe では拒否されます。

object[]

ガイドフレーム画像。キーフレームが 1 つの場合、type “video” のリクエストはシングルキーフレームの延長となり、常に 5s ブロック 1 つとして課金されます。

string

Base64 エンコードされた画像またはビデオデータ

string

ソースとして再利用する、以前に完了した生成の UUID。ray-3.2 の video_edit / video_reframe で使用されます。

string

MIME タイプ。data と併用する場合に必須です（ビデオソースの場合は url と併用する場合も必須。例: video_edit / video_reframe での video/mp4）。

string

公開アクセス可能な画像またはビデオの URL

boolean

生成されたクリップをループします。作成時のみ（type video）。

string

ray-3.2 video の出力解像度。デフォルトは 720p。360p はドラフト階層です。HDR には 720p または 1080p が必要です。指定可能な値: 360p、540p、720p、1080p

object

string

Base64 エンコードされた画像またはビデオデータ

string

ソースとして再利用する、以前に完了した生成の UUID。ray-3.2 の video_edit / video_reframe で使用されます。

string

MIME タイプ。data と併用する場合に必須です（ビデオソースの場合は url と併用する場合も必須。例: video_edit / video_reframe での video/mp4）。

string

公開アクセス可能な画像またはビデオの URL

boolean

Web 検索グラウンディングを有効にします

このスキーマは Router が GET /v2/models/luma_2/uni-1/openapi.json で提供するスキーマから生成されたものであり、リクエストがプロバイダーに到達する前に呼び出しを検証する際に使用される同一のドキュメントです。

出力

string

作成タイムスタンプ

string

プログラムで処理するための機械可読な失敗コード取り得る値: content_moderated、generation_failed、budget_exhausted、output_not_found

string

人間が読める形式の失敗の説明。FAILED の生成時のみ設定されます。成功した生成では null です。

string

生成識別子

string

使用されたモデル

object[]

生成された出力エントリ

string

メディアタイプ（例: 画像）

string

署名付き URL（1時間で失効）

string

生成の現在の状態取り得る値: queued、processing、completed、failed

string

実行する生成の種類。image/image_edit は uni-1 / uni-1-max モデルによって生成され、video/video_edit/video_reframe は ray-3.2 モデルによって生成されます。取り得る値: image、image_edit、video、video_edit、video_reframe

例

入力

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

出力

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

出荷前の確認

SDK は Idempotency-Key を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。リクエストが失敗すると、Router は理由を示す X-Comfy-Error-Type レスポンスヘッダーを送信します。422 は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味します。生成されたアセットは結果 URL の有効期限があるため、早めにダウンロードしてください。

ヘッダー

認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。

Router API の利用

モデルの検出、バリデーションエラー、リトライ、課金。

制限事項

Router が現在対応していないことと、代替手段。

Comfy で開発する

ワークフローの実行

Comfy Router

Comfy CLI

仕様

Comfy Router で Uni 1 を使用する

クイックスタート

スキーマ

入力

出力

例

入力

出力

出荷前の確認

ヘッダー

Router API の利用

制限事項

​クイックスタート

​スキーマ

​入力

​出力

​例

​入力

​出力

​出荷前の確認

ヘッダー

Router API の利用

制限事項

クイックスタート

スキーマ

入力

出力

例

入力

出力

出荷前の確認