> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Router で Veo 3.1 Lite Generate 001 を使用する

> Comfy Router 経由で veo/veo-3.1-lite-generate-001 を呼び出します: エンドポイント、リクエストの形状、Router が返すレスポンスについて説明します。

Veo から Comfy Router によって提供される `veo/veo-3.1-lite-generate-001` の API リファレンス。

**入力：** テキスト, 画像, ビデオ · **出力：** ビデオ + オーディオ

## クイックスタート

[Comfy ワークスペース](https://platform.comfy.org/profile/api-keys?onboarding=router)でキーを作成し、`COMFY_API_KEY` としてエクスポートします。Python と TypeScript のスニペットは Comfy SDK（`pip install comfy-sdk` および `npm install @comfyorg/sdk`）を使用しており、cURL スニペットは同じ呼び出しを生の HTTP で行うものです。

**モデル ID:** `veo/veo-3.1-lite-generate-001`

**エンドポイント:** `POST https://api.comfy.org/v2/models/veo/veo-3.1-lite-generate-001`

> [tab] 結果を待つ
>
> ```python Python theme={null}
> from comfy_sdk import Comfy
>
> # 環境変数から COMFY_API_KEY を読み取ります。
> # SDK は冪等キーを自動的に作成し、自動リトライのために再利用します。
> with Comfy() as client:
>     result = client.models.run(
>         "veo/veo-3.1-lite-generate-001",
>         {
>             "instances": [
>                 {
>                     "prompt": "a single red maple leaf falling onto still water, slow motion",
>                 },
>             ],
>             "parameters": {
>                 "durationSeconds": 4,
>                 "generateAudio": False,
>                 "sampleCount": 1,
>             },
>         },
>     )
>
> print(result)
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 環境変数から COMFY_API_KEY を読み取ります。
> // SDK は冪等キーを自動的に作成し、自動リトライのために再利用します。
> const { data } = await comfy.models.run("veo/veo-3.1-lite-generate-001", {
>   instances: [
>     {
>       prompt: "a single red maple leaf falling onto still water, slow motion",
>     },
>   ],
>   parameters: {
>     durationSeconds: 4,
>     generateAudio: false,
>     sampleCount: 1,
>   },
> });
>
> console.log(data);
> ```
>
> ```bash cURL theme={null}
> curl https://api.comfy.org/v2/models/veo/veo-3.1-lite-generate-001 \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"instances\": [{\"prompt\":\"a single red maple leaf falling onto still water, slow motion\"}], \"parameters\": {\"durationSeconds\":4,\"generateAudio\":false,\"sampleCount\":1}}"
> ```

> [tab] キューに送信して後で収集する
>
> 同じボディを `POST https://api.comfy.org/v2/models/veo/veo-3.1-lite-generate-001/requests` に送信します。Router は実行が受け付けられるとすぐに `201` と `request_id` を返し、結果は準備ができ次第、このプロセスからでも別のプロセスからでも収集できます。[キュー配信](https://docs.comfy.org/ja/development/comfy-router/queue.md)では、ステータス、キャンセル、収集について順を追って説明します。
>
> ```python Python theme={null}
> import asyncio
> from comfy_sdk import AsyncComfy
>
> # 環境変数から COMFY_API_KEY を読み取ります。
> # 各 submit() 呼び出しは独自の Idempotency-Key を発行し、自動リトライのために再利用します。
> async def main():
>     async with AsyncComfy() as client:
>         handle = await client.models.submit(
>             "veo/veo-3.1-lite-generate-001",
>             {
>                 "instances": [
>                     {
>                         "prompt": "a single red maple leaf falling onto still water, slow motion",
>                     },
>                 ],
>                 "parameters": {
>                     "durationSeconds": 4,
>                     "generateAudio": False,
>                     "sampleCount": 1,
>                 },
>             },
>         )
>         print("request_id:", handle.request_id)  # モデル ID と合わせれば、別のプロセスに必要なものはこれだけです
>
>         # リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の間待機します。
>         async for update in handle.iter_events():
>             print(update.status, update.queue_position)
>
>         # プロバイダー自身のペイロードで、models.run() が返す値と同じものです。
>         # 失敗またはキャンセルされたリクエストは、ここで型付きの Router エラーを発生させます。
>         result = await handle.get()
>
>     print(result)
>
> asyncio.run(main())
> ```
>
> ```typescript TypeScript theme={null}
> import { comfy } from "@comfyorg/sdk";
>
> // 環境変数から COMFY_API_KEY を読み取ります。
> // 各 submit() 呼び出しは独自の Idempotency-Key を発行し、自動リトライのために再利用します。
> const handle = await comfy.models.submit("veo/veo-3.1-lite-generate-001", {
>   instances: [
>     {
>       prompt: "a single red maple leaf falling onto still water, slow motion",
>     },
>   ],
>   parameters: {
>     durationSeconds: 4,
>     generateAudio: false,
>     sampleCount: 1,
>   },
> });
> console.log("requestId:", handle.requestId); // モデル ID と合わせれば、別のプロセスに必要なものはこれだけです
>
> // リクエストが完了するまでポーリングし、サーバーが指定する Retry-After の間待機します。
> for await (const update of handle.events()) {
>   console.log(update.status, update.queuePosition);
> }
>
> // models.run() が返すのと同じ結果です。失敗またはキャンセルされたリクエストは、ここで reject されます。
> const result = await handle.get();
>
> console.log(result.data);
> ```
>
> ```bash cURL theme={null}
> # 1. 送信。Router は request_id、status_url、response_url、cancel_url とともに 201 を返します。
> curl https://api.comfy.org/v2/models/veo/veo-3.1-lite-generate-001/requests \
>   -H "X-API-Key: $COMFY_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H "Content-Type: application/json" \
>   -d "{\"instances\": [{\"prompt\":\"a single red maple leaf falling onto still water, slow motion\"}], \"parameters\": {\"durationSeconds\":4,\"generateAudio\":false,\"sampleCount\":1}}"
>
> # 2. ステータスが COMPLETED になるまでポーリングし、各レスポンスが指定する Retry-After 秒だけ待機します。
> REQUEST_ID="<request_id from the 201 body>"
> curl -i https://api.comfy.org/v2/models/veo/veo-3.1-lite-generate-001/requests/$REQUEST_ID/status \
>   -H "X-API-Key: $COMFY_API_KEY"
>
> # 3. 収集。200 はモデルのネイティブ出力、まだ実行中はステータスボディとともに 202。
> curl https://api.comfy.org/v2/models/veo/veo-3.1-lite-generate-001/requests/$REQUEST_ID \
>   -H "X-API-Key: $COMFY_API_KEY"
> ```

## スキーマ

### 入力

**instances** `object[]`

**instances\[].cameraControl** `string`

カメラの動きの種類。画像を指定する必要があります。

取り得る値: `fixed`, `pan_left`, `pan_right`, `tilt_up`, `tilt_down`, `truck_left`, `truck_right`, `pedestal_up`, `pedestal_down`, `push_in`, `pull_out`

**instances\[].image** `object`

ビデオ生成をガイドするためのオプションの先頭フレーム画像

**instances\[].image.bytesBase64Encoded** `string (byte)`

Base64 でエンコードされた画像データ

形式: `byte`

**instances\[].image.gcsUri** `string`

画像の Cloud Storage URI。非 BYOK リクエストでは、Comfy が所有するバケットを指す `gs://` URI（またはその `https://storage.googleapis.com` 形式）は 400 で拒否されます。ただし、そのオブジェクトが自分の `POST /customers/storage` プレフィックス配下にある場合、または以前の Veo 生成が自分のために書き込んだビデオである場合を除きます。

**instances\[].image.mimeType** `string`

画像の MIME タイプ (image/jpeg または image/png)

取り得る値: `image/jpeg`, `image/png`

**instances\[].lastFrame** `object`

オプションの末尾フレーム画像。image と併用して、先頭フレームと末尾フレームの間のビデオを生成します。Veo 3.0+ モデルでサポートされています。

**instances\[].lastFrame.bytesBase64Encoded** `string (byte)`

Base64 でエンコードされた画像データ

形式: `byte`

**instances\[].lastFrame.gcsUri** `string`

画像の Cloud Storage URI。非 BYOK リクエストでは、Comfy が所有するバケットを指す `gs://` URI（またはその `https://storage.googleapis.com` 形式）は 400 で拒否されます。ただし、そのオブジェクトが自分の `POST /customers/storage` プレフィックス配下にある場合、または以前の Veo 生成が自分のために書き込んだビデオである場合を除きます。

**instances\[].lastFrame.mimeType** `string`

画像の MIME タイプ (image/jpeg または image/png)

取り得る値: `image/jpeg`, `image/png`

**instances\[].mask** `object`

ビデオ編集用のオプションのマスク。入力ビデオに適用されます。

**instances\[].mask.bytesBase64Encoded** `string (byte)`

Base64 でエンコードされたマスクのバイトデータ

形式: `byte`

**instances\[].mask.gcsUri** `string`

マスクファイルの Cloud Storage URI。非 BYOK リクエストでは、Comfy が所有するバケットを指す `gs://` URI（またはその `https://storage.googleapis.com` 形式）は 400 で拒否されます。ただし、そのオブジェクトが自分の `POST /customers/storage` プレフィックス配下にある場合、または以前の Veo 生成が自分のために書き込んだビデオである場合を除きます。

**instances\[].mask.maskMode** `string`

マスクの適用方法

取り得る値: `insert`, `remove`, `remove_static`, `outpaint`

**instances\[].mask.mimeType** `string`

マスクの MIME タイプ (image/png、image/jpeg、image/webp、またはビデオ形式)

**instances\[].prompt** `string` *required*

生成するビデオのテキスト説明

**instances\[].referenceImages** `object[]`

ビデオ生成をガイドするためのオプションの参照画像。最大 3 つのアセット画像または 1 つのスタイル画像をサポートします。Veo 3.1 モデル (プレビュー) でサポートされています。

**instances\[].referenceImages\[].image** `object` *required*

**instances\[].referenceImages\[].image.bytesBase64Encoded** `string (byte)`

Base64 でエンコードされた画像データ

形式: `byte`

**instances\[].referenceImages\[].image.gcsUri** `string`

画像の Cloud Storage URI。非 BYOK リクエストでは、Comfy が所有するバケットを指す `gs://` URI（またはその `https://storage.googleapis.com` 形式）は 400 で拒否されます。ただし、そのオブジェクトが自分の `POST /customers/storage` プレフィックス配下にある場合、または以前の Veo 生成が自分のために書き込んだビデオである場合を除きます。

**instances\[].referenceImages\[].image.mimeType** `string`

画像の MIME タイプ (image/jpeg または image/png)

取り得る値: `image/jpeg`, `image/png`

**instances\[].referenceImages\[].referenceId** `string`

参照画像のオプションの識別子

**instances\[].referenceImages\[].referenceType** `string` *required*

参照画像の種類

取り得る値: `asset`, `style`

**instances\[].video** `object`

ビデオ拡張または編集用のオプションの入力ビデオ。image および referenceImages とは併用できません。

**instances\[].video.bytesBase64Encoded** `string (byte)`

Base64 でエンコードされたビデオのバイトデータ

形式: `byte`

**instances\[].video.gcsUri** `string`

入力ビデオの Cloud Storage URI。非 BYOK リクエストでは、Comfy が所有するバケットを指す `gs://` URI（またはその `https://storage.googleapis.com` 形式）は 400 で拒否されます。ただし、そのオブジェクトが自分の `POST /customers/storage` プレフィックス配下にある場合、または以前の Veo 生成が自分のために書き込んだビデオである場合を除きます。

**instances\[].video.mimeType** `string`

ビデオの MIME タイプ

取り得る値: `video/mov`, `video/mpeg`, `video/mp4`, `video/mpg`, `video/avi`, `video/wmv`, `video/mpegps`, `video/x-flv`

**parameters** `object`

**parameters.aspectRatio** `string`

生成されるビデオのアスペクト比。デフォルト: 16:9

取り得る値: `16:9`, `9:16`

**parameters.compressionQuality** `string`

ビデオの圧縮品質。デフォルト: optimized

取り得る値: `optimized`, `lossless`

**parameters.durationSeconds** `number`

生成されるビデオの目標再生時間 (秒)。Veo 2: 5-8。Veo 3/3.1: 4、6、または 8。デフォルト: 8

**parameters.enhancePrompt** `boolean`

より高品質にするためにプロンプトを自動的に改善します。デフォルトは true です。

**parameters.fps** `integer`

生成されるビデオのフレームレート（1 秒あたりのフレーム数）

**parameters.generateAudio** `boolean`

ビデオと一緒にオーディオを生成するかどうか。デフォルトは true。Veo 3.0+ モデルでサポートされています。

**parameters.negativePrompt** `string`

生成されるビデオで避けるべき内容を記述したテキスト

**parameters.personGeneration** `string`

生成されるビデオ内の人物を制御します。デフォルト: allow\_adult。
`ALLOW` と `BLOCK` も受け付けられます。これは Veo2GenVidRequest の personGeneration enum がこれらを保持しているのと同じ互換性の理由によるものです（そのコンポーネントの注記を参照）。ComfyUI の Veo 3 パートナーノード（comfy\_api\_nodes/nodes\_veo2.py）は、veo-3.1-generate-001、veo-3.1-fast-generate-001、veo-3.1-lite-generate-001 に対して `/proxy/veo/{model}/generate` へ、常にこの 2 つの綴りのいずれかを送信し、Vertex 自身の綴りを送ることはありません。これら 3 つの ID が、このコンポーネントが Router 入力スキーマとなる対象です。これらの ID のいずれかに対する Router ディスパッチ（`model_provider=veo`）では、同期でもキュー中でも（`/v2/models/veo/{model}/requests`）、リクエストが Vertex に到達する前に `ALLOW` は `allow_adult` に、`BLOCK` は `dont_allow` にマッピングされます（routerVeoMapPersonGeneration、server/middleware/router\_veo\_person\_generation.go）。これは Vertex 自身がどちらの綴りも受け付けないためです。v1 の `/proxy/veo/:modelId/generate` を直接呼び出す場合はどちらでも影響を受けません。comfy-api は `/proxy/*` にリクエストバリデーターをインストールしないため、この enum はそこではもともと強制されないドキュメントであり、Router 専用のマッピングもその呼び出しでは実行されません。

取り得る値: `dont_allow`, `allow_adult`, `allowAll`, `ALLOW`, `BLOCK`

**parameters.pubsubTopic** `string`

進捗更新のための Cloud Pub/Sub トピック（projects/\{project}/topics/\{topic}）。Comfy の認証情報を使う（non-BYOK）リクエストでは受け付けられません。指定されている場合、generate ルートは 400 を返します。これは、操作が Comfy のプロジェクトで実行され、Vertex が Comfy のサービスエージェントとして公開することになるためです。受け付けられるのは bring-your-own-key リクエストのみで、その場合 Vertex はあなた自身のプロジェクトでトピックの許可を評価します。

**parameters.resizeMode** `string`

入力画像のリサイズ方法。デフォルト: pad

取り得る値: `pad`, `crop`

**parameters.resolution** `string`

出力ビデオの解像度。Veo 3.0+ モデルでサポートされています。デフォルト: 720p

取り得る値: `720p`, `1080p`, `4k`

**parameters.sampleCount** `integer`

生成するビデオの数。指定しない場合は 1 本のビデオが生成されます。

範囲: `1` から `4`

**parameters.seed** `integer`

決定論的な出力のためのランダムシード。sampleCount > 1 の場合は、ビデオごとに異なるシードが使用されます。

形式: `uint32`

**parameters.storageUri** `string`

生成されたビデオの保存先となる省略可能な Cloud Storage の場所（`gs://` URI）。
自分自身のバケットを指定する必要があります。bring-your-own-key 以外では、このルートは自分のものではなく Comfy 自身の Google Cloud 認証情報で実行されるため、Comfy が所有するバケット内の保存先は、Comfy のサービスアカウントが共有レイアウトに対して実行し、Comfy のプロジェクトに課金される書き込みになります。そのような値を指定したリクエストは 400 で拒否され、何も生成されません。例外は 1 つだけで、プラットフォームストレージが有効な同期 Comfy Router 呼び出し（`POST /v2/models/{provider}/{model}`）です。この場合、Router 自身の Veo または Gemini アセットバケットを指す値は、その呼び出しのために Router が自分のプラットフォームプレフィックス配下で発行する保存先に置き換えられ、その Router が発行した正確な保存先だけが通されます。キュー中の Router 送信（`POST /v2/models/{provider}/{model}/requests`）ではそのような置き換えは行われないため、他の Comfy 所有バケットと同様にその値を 400 で拒否します。それ以外の保存先は変更されずに Vertex へ転送され、アクセス権の付与は自分の責任です。bring-your-own-key の呼び出しは自分のプロジェクトで実行され、送信されたまま転送されます。

**parameters.task** `string`

ビデオ生成リクエストの操作タイプ

取り得る値: `textToVideo`, `imageToVideo`, `referenceToVideo`, `edit`, `extend`, `upscale`

Router が `GET /v2/models/veo/veo-3.1-lite-generate-001/openapi.json` で提供するスキーマから生成されています。これは、リクエストがプロバイダーに到達する前に Router が呼び出しを検証する際に使用するドキュメントと同じものです。

### 出力

**done** `boolean`

操作が完了したかどうか

**error** `object`

エラーの詳細。操作が失敗した場合に存在します

**error.code** `integer`

gRPC エラーコード

**error.message** `string`

エラーメッセージ

**name** `string`

操作リソース名

**response** `object`

予測レスポンス。done が true の場合に存在します

**response.\@type** `string`

**response.raiMediaFilteredCount** `integer`

責任ある AI ポリシーによってフィルタリングされたビデオの数

**response.raiMediaFilteredReasons** `string[]`

ビデオが責任ある AI ポリシーによってフィルタリングされた理由

**response.videos** `object[]`

**response.videos\[].bytesBase64Encoded** `string`

Base64 エンコードされたビデオコンテンツ

**response.videos\[].gcsUri** `string`

生成されたビデオの Cloud Storage URI

**response.videos\[].mimeType** `string`

ビデオの MIME タイプ (video/mp4)

## 例

### 入力

```json theme={null}
{
  "instances": [
    {
      "prompt": "a single red maple leaf falling onto still water, slow motion"
    }
  ],
  "parameters": {
    "durationSeconds": 4,
    "generateAudio": false,
    "sampleCount": 1
  }
}
```

### 出力

```json theme={null}
{
  "done": true,
  "name": "projects/example-project/locations/us-central1/publishers/google/models/veo-3.1-fast-generate-001/operations/1a2b3c4d",
  "response": {
    "@type": "type.googleapis.com/cloud.ai.large_models.vision.GenerateVideoResponse",
    "raiMediaFilteredCount": 0,
    "videos": [
      {
        "gcsUri": "https://storage.googleapis.com/EXAMPLE_BUCKET/veo/USER_ID/REQUEST_ID/sample_0.mp4",
        "mimeType": "video/mp4"
      }
    ]
  }
}
```

## 出荷前の確認

SDK は `Idempotency-Key` を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。

リクエストが失敗すると、Router は理由を説明する `X-Comfy-Error-Type` レスポンスヘッダーを送信します。`422` は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味し、`413` はリクエスト本文が Router の受け入れ可能なサイズを超えていたことを意味します。生成されたアセットは [結果 URL の有効期限](https://docs.comfy.org/ja/development/comfy-router/reference.md#結果アセット) があるため、早めにダウンロードしてください。

上記のフィールド説明に記載されているサイズ制限は、プロバイダーの仕様から引用した、そのフィールドに対するプロバイダー自身の上限です。Router はリクエスト本文全体に対して別の上限を適用し、base64 エンコードされたメディアもこれにカウントされます。[リクエスト本文のサイズ](https://docs.comfy.org/ja/development/comfy-router/limitations.md) を参照してください。

このページは、Comfy Router 経由で呼び出す 1 つのパートナーモデルについて説明しています。同じ `comfy-sdk` / `@comfyorg/sdk` パッケージには、Comfy Cloud 上で ComfyUI のワークフローグラフ全体を実行するための 2 つ目のクライアントも含まれています: `Comfy(api_key=...)` / `new Comfy({ apiKey })`、および `client.workflows`、`client.assets`、`client.jobs`。[Comfy SDKs](https://docs.comfy.org/ja/development/api-development/sdks.md) を参照してください。

> [card] [ヘッダー](https://docs.comfy.org/ja/development/comfy-router/headers.md)
>
> 認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。

> [card] [Router API の利用](https://docs.comfy.org/ja/development/comfy-router/api.md)
>
> モデルの検出、バリデーションエラー、リトライ、課金。

> [card] [制限事項](https://docs.comfy.org/ja/development/comfy-router/limitations.md)
>
> Router が現在対応していないことと、代替手段。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.