クイックスタート
あなたの Comfy ワークスペースでキーを作成し、COMFY_API_KEY としてエクスポートします。Python と TypeScript のスニペットは Comfy SDK(pip install comfy-sdk および npm install @comfyorg/sdk)を使用しています。cURL のスニペットは、同じ呼び出しを生の HTTP で実行するものです。
モデル ID: wan/wan2.7-i2v
エンドポイント: POST https://api.comfy.org/v2/models/wan/wan2.7-i2v
- 結果を待つ
- キューに送信して後で収集
同じボディを
POST https://api.comfy.org/v2/models/wan/wan2.7-i2v/requests に送信します。Router は実行が受け付けられるとすぐに 201 と request_id を返し、結果は準備ができ次第、このプロセスからでも別のプロセスからでも収集できます。キュー配信 では、ステータス、キャンセル、収集について順を追って説明します。スキーマ
入力
object
必須
プロンプトなど、基本情報を入力します。
string
オーディオファイルのダウンロード URL。対応形式: mp3 と wav。reference_video_urls とは併用できません。
string
先頭フレーム画像の URL、または Base64 エンコードされたデータ。wan2.5-i2v-preview および
wan2.6-i2v モデルでは必須です。happyhorse-1.x の i2v 表記は、先頭フレームをここでは
受け取りません。type が first_frame のメディア要素として受け取ります(後述の media を
参照)。また、wan2.6-i2v では成功する img_url ボディも、happyhorse-1.0-i2v および
happyhorse-1.1-i2v ではプロバイダーに拒否されます。wan2.7/wan3.0 の表記も参照アセットを
media で受け取ります。画像形式: JPEG、JPG、PNG、BMP、WEBP。
解像度: 360-2000 ピクセル。ファイルサイズ: 最大 10MB。
object[]
メディアアセットのリスト。ビデオ生成用の参照素材(画像、オーディオ、ビデオ)を
指定します。各要素は type と url フィールドを含みます。このフィールドはこの
コンポーネントから提供されるすべてのモデルで共通であり、どのモデルがどの type 値を
受け付けるか、また画像やビデオの入力を img_url や reference_video_urls ではなく
ここで受け取るかどうかは、モデルによって異なります。モデルごとの対応 type 値:
- wan2.7-i2v: first_frame、last_frame、driving_audio、first_clip。first_frame と last_frame: JPEG/JPG/PNG/BMP/WEBP、1 辺あたり 240-8000 ピクセル、アスペクト比 1:8 から 8:1 の間、最大 20MB、公開 URL または data:{MIME_type};base64,… URL。 driving_audio(WAV/MP3、2-30 秒、最大 15MB)と first_clip(MP4/MOV、2-10 秒、1 辺あたり 240-4096 ピクセル、最大 100MB): 公開 HTTP/HTTPS URL。インラインの data: URL は受け付けられません。
- wan2.7-r2v: first_frame(任意、最大 1 件)、reference_image、reference_video。少なくとも 1 つの reference_image または reference_video が必要で、reference_image と reference_video の合計は最大 5 件です。first_frame と reference_image: JPEG/JPG/PNG/BMP/WEBP (アルファチャンネルなし)、1 辺あたり 240-8000 ピクセル、アスペクト比 1:8 から 8:1 の間、最大 20MB、公開 URL または data:{MIME_type};base64,… URL。reference_video: 公開 HTTP/HTTPS URL。インラインの data: URL は受け付けられません。
- wan2.7-videoedit: video(正確に 1 件、編集対象のクリップ: MP4/MOV、2-10 秒、 1 辺あたり 240-4096 ピクセル、最大 100MB、公開 HTTP/HTTPS URL。インラインの data: URL は受け付けられません)に加えて、任意で 0 から 4 件の reference_image(JPEG/JPG/PNG/BMP/WEBP、 1 辺あたり 240-8000 ピクセル、アスペクト比 1:8 から 8:1 の間、最大 20MB、公開 URL または data:{MIME_type};base64,… URL)。
- wan3.0-video, wan3.0-video-prime: first_frame(最大 1 件)、last_frame(最大 1 件)、 reference_image(最大 10 件)、reference_video(最大 5 クリップ、合計再生時間 <= 15s)、 reference_audio(最大 5 クリップ、合計再生時間 <= 15s)、file(最大 1 件、link とは併用 不可)、link(最大 1 件、file とは併用不可)。reference_*/file/link タイプ と first_frame/last_frame タイプは、同一リクエスト内で排他的です。 配列の順序がプロンプト内のアセットの参照順序を定義します(Image 1、Video 1、 Audio 1、…)。first_frame、last_frame、reference_image: JPEG/JPG/PNG/BMP/WEBP、 1 辺あたり 240-8000 ピクセル、アスペクト比 最大 8:1、最大 20MB、公開 URL または data:{MIME_type};base64,… URL。reference_video、reference_audio、file、link: 公開 HTTP/HTTPS URL。インラインの data: URL は受け付けられません。
- happyhorse-1.0-i2v, happyhorse-1.1-i2v: first_frame のみ、正確に 1 件。これらの表記は 先頭フレームを img_url ではなくここで受け取ります。少なくとも 300x300 ピクセル、アスペクト比 1:2.5 から 2.5:1 の間、JPEG/JPG/PNG/WEBP、最大 20MB、公開 URL または data:{MIME_type};base64,… URL。
- happyhorse-1.0-r2v, happyhorse-1.1-r2v: reference_image のみ、1 から 9 件。これが このモデル唯一の参照入力です。最短辺が少なくとも 400 ピクセル、JPEG/JPG/PNG/WEBP、 最大 20MB、公開 URL または data:{MIME_type};base64,… URL。reference_video は この操作の入力タイプではありません。
- happyhorse-1.0-video-edit: video(正確に 1 件、編集対象のクリップ: MP4/MOV、3-60 秒、長辺 最大 4096 ピクセル、短辺 少なくとも 360 ピクセル、アスペクト 比 1:2.5 から 2.5:1 の間、最大 100MB、公開 HTTP/HTTPS URL。インラインの data: URL は受け付けられません)に加えて、任意で 0 から 5 件の reference_image(JPEG/JPG/PNG/BMP/WEBP、 少なくとも 300x300 ピクセル、アスペクト比 1:2.5 から 2.5:1 の間、最大 20MB、公開 URL または data:{MIME_type};base64,… URL)。
- happyhorse-1.0-t2v, happyhorse-1.1-t2v, wan2.7-t2v, wan2.6-t2v, wan2.5-t2v-preview: テキストから動画への操作。対応するパートナーの参照ドキュメントにはメディア入力の記載が ないため、このフィールドは未設定のままにしてください。
- wan2.5-i2v-preview, wan2.6-i2v, wan2.6-r2v: このコンポーネントはこれらの表記向けの メディア語彙を列挙していません。wan2.5-i2v-preview と wan2.6-i2v は先頭 フレームを img_url で受け取り、wan2.6-r2v は参照クリップを reference_video_urls で 受け取ります。 上記のモデルごとの件数はこのスキーマの制約ではなく、パートナーの制約です。media には minItems/maxItems が宣言されていません。許容される type とその上限はモデルごとに 異なるためです。スキーマが受け入れてもプロバイダーが受け入れるとは限りません。逆方向も 同様で、上記のアセットごとの「最大 20MB」という数値(画像入力に対する上限であり、 インラインで送信できる唯一の入力です)は、最終的に扱うアセットに対するパートナーの 上限であり、アセットが公開 URL の場合には記載どおりに適用されます。そのバイト列が Comfy を通らないためです。インラインの data:{MIME_type};base64,… URL は Comfy を通るため、転送時の上限にも直面します。Comfy Router の POST ボディは合計 100 MiB に制限され、それを超えると 413 が返され、base64 は ペイロードを約 4/3 に膨らませるため、およそ 75 MB を超える単一のインラインアセットは、 ここに挙げたパートナーのルールに到達する前に拒否されます。そのサイズでは、パートナー自身の20MB の上限はインラインであれば余裕を持って収まるため、アセット1件の場合はパートナーのルールが制約となります。一方、トランスポートの上限は複数のアセットにまたがる場合に制約となります。100 MiB の Router 上限は各要素ではなくリクエスト全体を制限するためです。これらの上限に近いものは公開 URL として送信してください。
string
必須
メディアアセットの種類指定可能な値:
first_frame, last_frame, driving_audio, first_clip, reference_image, reference_video, reference_audio, video, file, linkstring
必須
メディアファイルの URL: 公開 HTTP/HTTPS URL、または(上記の
media の説明で各モデルごとに挙げられている IMAGE 入力に限り)インラインの data:{MIME_type};base64,... URL です。各モデルで対象となる IMAGE 入力は次のとおりです。wan2.7-i2v では first_frame と last_frame、wan2.7-r2v では first_frame と reference_image、wan2.7-videoedit では reference_image、wan3.0-video と wan3.0-video-prime では first_frame、last_frame、reference_image、happyhorse-1.0-i2v と happyhorse-1.1-i2v では first_frame、happyhorse-1.0-r2v と happyhorse-1.1-r2v では reference_image、happyhorse-1.0-video-edit では reference_image です。これらのモデルのいずれにおいても、ビデオ、オーディオ、ファイル、リンクの入力はインラインの data: URL を受け付けません。パートナー自身のアップロードサービスによる oss://dashscope-instant の一時 URL、または(wan2.7-videoedit では)Asset Center の asset_id は、それをアップロードした Alibaba Cloud アカウントに対してのみ解決されます。Comfy は自身のキーでモデル呼び出しを行うものであり、アップロード経路を公開していないため、呼び出し元自身の oss:// URL や asset_id はサポートされる入力ではありません。このフィールドは URL スキームを検証しないため、そのような値はここで拒否されることなく、そのままパートナーへ転送されます。モデルごとのサイズとピクセルの上限、およびインラインペイロードを全体として制限する 100 MiB の Router リクエストボディ上限については、media の説明を参照してください。string
ネガティブプロンプトは、ビデオ画面に表示したくないコンテンツを記述するために使用します
string
テキストプロンプト。中国語と英語をサポートし、長さは 800 文字以内です
(wan3.0-video では最大 20,000 文字。上限を超えたコンテンツは切り詰められます)。
複数の参照ビデオを使用する wan2.6-r2v では、‘character1’、‘character2’ などを使用して、
参照ビデオの順序で被写体を参照します。例: “Character1 sings on the roadside, Character2 dances beside it”
wan3.0-video の参照モードでは、‘Image 1’、‘Video 1’、‘Audio 1’ などを使用して、
media 配列内の対応する順序でメディアアセットを参照します。
string[]
wan2.6-r2v モデル専用の参照ビデオ URL。1~3 件のビデオ URL の配列。
入力の制限:
- 形式: mp4, mov
- 数量: 1~3 本のビデオ
- 単一ビデオの長さ: 2~30 秒
- 単一ファイルサイズ: 最大 30MB
- audio_url と併用できません 参照再生時間: 単一ビデオは最大 5 秒、2 本のビデオはそれぞれ最大 2.5 秒、3 本のビデオはそれに比例して短くなります。 課金: 実際に使用した参照再生時間に基づきます。
string
ビデオエフェクトテンプレート名。任意。現在サポートされているのは squish、flying、carousel です。使用時は prompt パラメータは無視されます。
string
呼び出すモデルの ID。このコンポーネントでは制約されません。Comfy Router が
POST /v2/models/wan/{model} の {model} パスセグメントから設定するため、Router の呼び出し元はこれを省略します。POST /proxy/wan/api/v1/services/aigc/video-generation/video-synthesis への直接の v1 呼び出しでは必ず指定する必要があり、受け入れられる表記の列挙はその操作自身のコンポーネントである WanVideoGenerationRequest にあります。object
ビデオ処理パラメータ
boolean
デフォルト:"true"
ビデオにオーディオを追加するかどうか。wan3.0-video と wan3.0-video-prime でのみサポートされます。プロバイダーは他の wan モデルにはそのような切り替えを記載していません。
string
デフォルト:"\"auto\""
wan2.7-videoedit モデルのビデオオーディオ設定。
- auto (デフォルト): モデルがプロンプトの内容に基づいてインテリジェントに判断します
-
origin: 入力ビデオのオリジナルのオーディオを強制的に保持します
指定可能な値:
auto,origin
integer
デフォルト:"5"
生成されるビデオの再生時間(秒):
- wan2.5 モデル: 5 秒または 10 秒
- wan2.6-t2v, wan2.6-i2v: 5 秒、10 秒、または 15 秒
- wan2.6-r2v: 5 秒または 10 秒のみ(15 秒はサポートされません)
- wan2.7-i2v, wan2.7-t2v: [2, 15] の整数
- wan2.7-r2v, wan2.7-videoedit: [2, 10] の整数
-
wan3.0-video: ビデオ入力なしの場合は [2, 30] の整数。ビデオ入力ありの場合は、
入力ビデオの再生時間 + 出力ビデオの再生時間の合計が 30 秒を超えてはなりません。
-1 を指定すると、モデルが適切な再生時間を選択するスマート再生時間モードが有効になります
このプロキシは、[-1, 30] の範囲外の再生時間に対して 400 を返します。
範囲:
-1~30
boolean
デフォルト:"true"
プロンプトのインテリジェントな書き換えを有効にするかどうか。デフォルトは true です
string
生成されるビデオのアスペクト比。wan2.7 および wan3.0 モデル専用です。
wan2.7 モデルでは、指定しない場合は解像度ティアに基づいてデフォルトが決まります。
wan3.0-video では、adaptive(デフォルト)が入力メディアの比率と意図に基づいて
適切なアスペクト比を自動的に推奨します。指定可能な値:
adaptive, 16:9, 9:16, 1:1, 4:3, 3:4string
解像度レベル。サポートされる値はモデルによって異なります:
- wan2.5-i2v-preview: 480P, 720P, 1080P
- wan2.6 モデル (t2v, i2v, r2v): 720P, 1080P のみ(480P はサポートされません)
- wan2.7 モデル (i2v, t2v, r2v, videoedit): 720P, 1080P(デフォルトは 1080P)
- wan3.0-video、wan3.0-video-prime: 480P、720P、1080P(アップストリームのデフォルトは 1080P)
- happyhorse-1.0-*(t2v、i2v、r2v、video-edit): 720P、1080P
-
happyhorse-1.1-*(t2v、i2v、r2v): 480P、720P、1080P
このプロキシは、resolution と size のどちらも指定していないビデオ生成リクエストを拒否します。resolution のティアが課金レートを決定するためです。検証の前に resolution を大文字に変換し、その大文字化した値を転送します。また、この enum に含まれない値には 400 を返し、上記で 480P に対応しないものとして挙げた wan2.6、wan2.7、happyhorse-1.0 モデルでは 480P(resolution として送信された場合でも、480P の size として送信された場合でも)に対して 400 を返します。
指定可能な値:
480P、720P、1080P
integer
乱数シード。モデルが生成するコンテンツのランダム性を制御するために使用します範囲:
0 から 2147483647string
デフォルト:"\"single\""
インテリジェントなマルチレンズ制御。prompt_extend が有効な場合にのみ機能します。
wan2.6 および wan2.7-r2v モデル用。
- single: 単一ショットのビデオ(デフォルト)
-
multi: マルチショットのビデオ
指定可能な値:
multi、single
string
幅高さ形式のビデオ解像度。サポートされる解像度はモデルによって異なります:
wan2.5 T2V の場合: 480P(480832、832480、624624)、720P、1080P の各サイズ
wan2.6 T2V/R2V の場合(480P なし):
720P: 1280720、7201280、960960、1088832、8321088
1080P: 19201080、10801920、14401440、16321248、12481632
size と resolution の両方を送信した場合、課金されるティアを選択するのは size であり、resolution はモデルに対してこのプロキシが受け付ける値である必要があります。480P の size は、解像度の説明で 480P に対応しないと記載されているすべてのモデルで 400 を返します。
boolean
デフォルト:"false"
ウォーターマークロゴを追加するかどうか。ウォーターマークは右下隅に配置されます
GET /v2/models/wan/wan2.7-i2v/openapi.json で提供するスキーマから生成されています。これは、リクエストがプロバイダーに到達する前に呼び出しの検証に使用されるドキュメントと同じものです。
出力
object
必須
string
インテリジェントな書き換え後の実際のプロンプト(ビデオタスク向け)
string
音声生成を伴うI2VタスクのオーディオURL
string
失敗したリクエストのエラーコード(リクエストが成功した場合は返されません)
string
タスクの完了時間
string
失敗したリクエストに関する詳細情報(リクエストが成功した場合は返されません)
string
オリジナルの入力プロンプト(ビデオタスク向け)
object[]
画像生成タスクのタスク結果のリスト
string
インテリジェントな書き換え後の実際のプロンプト(有効な場合)
string
画像のエラーコード(一部のタスクが失敗した場合に返されます)
string
画像のエラー情報(一部のタスクが失敗した場合に返されます)
string
オリジナルの入力プロンプト
string
生成された画像のURLアドレス
string
タスクの実行時間
string
タスクの送信時間
string
必須
タスクID
object
画像生成タスクのタスク結果統計
integer
失敗したタスクの数
integer
成功したタスクの数
integer
タスクの総数
string
必須
タスクのステータス指定可能な値:
PENDING、RUNNING、SUCCEEDED、FAILED、CANCELED、UNKNOWNstring
完了したビデオ生成タスクのビデオURL。リンクの有効期間は24時間
string
必須
一意のリクエスト識別子
object
出力情報の統計。成功した結果のみがカウントされます
integer
ビデオ解像度レベル(I2Vおよびwan3.0-videoタスク)
number
生成されたビデオの再生時間(秒)(I2Vおよびwan3.0-videoタスク)
integer
生成されたビデオのフレームレート(wan3.0-videoタスク)
integer
生成された画像の数(T2IおよびI2Iタスク)
number
入力ビデオの再生時間(秒)。ビデオ入力がない場合は 0.0(wan3.0-videoタスク)
number
出力ビデオの再生時間(秒)(wan3.0-videoタスク)
string
生成されたビデオのアスペクト比(例: 16:9)(wan3.0-videoタスク)
string
画像の解像度(T2IおよびI2Iタスク)
integer
生成されたビデオの数(T2Vタスク)
number
生成されたビデオの再生時間(秒)(T2Vタスク)
string
ビデオの解像度比率(T2Vタスク)
string
失敗したリクエストのエラーコード。
output の下ではなく、エンベロープの ROOT で報告されます(リクエストが成功した場合は返されません)。string
失敗したリクエストに関する詳細情報。
output の下ではなく、エンベロープの ROOT で報告されます(リクエストが成功した場合は返されません)。output.message にフォールバックする前にこちらを確認してください。例
入力
出力
出荷前の確認
SDK はIdempotency-Key を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。
リクエストが失敗すると、Router は理由を説明する X-Comfy-Error-Type レスポンスヘッダーを送信します。422 は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味し、413 はリクエスト本文が Router の受け入れ可能なサイズを超えていたことを意味します。生成されたアセットは 結果 URL の有効期限 があるため、早めにダウンロードしてください。
上記のフィールド説明に記載されているサイズ制限は、プロバイダーの仕様から引用した、そのフィールドに対するプロバイダー自身の上限です。Router はリクエスト本文全体に対して別の上限を適用し、base64 エンコードされたメディアもこれにカウントされます。リクエスト本文のサイズ を参照してください。
このページは、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 を参照してください。
ヘッダー
認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。
Router API の利用
モデルの検出、バリデーションエラー、リトライ、課金。
制限事項
Router が現在対応していないことと、代替手段。