https://api.comfy.org
以下のすべてのエンドポイントは認証が必要です。X-API-Key: <api-key> または Authorization: Bearer <jwt> を送信してください。
Comfy API キーは Bearer トークンとして送信することもできます。両方の認証ヘッダーが指定された場合、X-API-Key が優先されます。キーと JWT の違いについては認証ヘッダーを、アクセス要件についてはクイックスタートを参照してください。
エンドポイント
GET /v2/models
Comfy Router が実行できるモデルを一覧表示します。
利用可能なモデル ID と課金情報を一覧表示します。has_more が true の間は next_cursor を使用します。
パラメータ
レスポンス
GET /v2/models/{provider}/{model}
正規のモデル ID でパートナーモデル 1 件のカタログエントリを読み取ります。
カタログ全体を一覧表示せずに、1 つのモデルの詳細を読み取ります。
パラメータ
レスポンス
POST /v2/models/{provider}/{model}
正規のモデル ID を指定してパートナーモデルを同期的に実行します。
モデルを実行し、完了した結果を同じレスポンスで受け取ります。
パラメータ
リクエストボディ
application/json: RouterModelInput(必須)
パートナーモデルのネイティブな JSON 入力。プロバイダーへそのまま転送されます。
レスポンス
GET /v2/models/{provider}/{model}/openapi.json
1つのパートナーモデルの入力スキーマと出力スキーマをOpenAPIドキュメントとして読み取ります。
1つのモデルの入力スキーマと出力スキーマを単体のOpenAPIドキュメントとして読み取ります。
パラメータ
レスポンス
POST /v2/models/{provider}/{model}/requests
パートナーモデルの実行をキューに送信し、すぐに戻ります。
Comfy Router の QUEUED 配信モードです。リクエストボディは、POST /v2/models/{provider}/{model} がこのモデルに対して受け付けるものと同じパートナー固有の JSON 入力です。1 つのボディ形状、モデルごとに 1 つのスキーマ、2 つの配信モードがありますが、このルートは結果を待つために接続を保持しません。実行を受理し、ハンドルとともに 201 を返します。呼び出し側は後で、以下の 3 つの読み取りを通じて結果を取得します。
パラメータ
リクエストボディ
application/json — RouterModelInput(必須)
パートナーモデル固有の JSON 入力で、同期ルートがこのモデルに対して受け付けるボディと同一です。実行が受理される前に、モデル自身の入力スキーマに対して検証されます。そのため、モデルが拒否するボディは、数分後に失敗するキュー中のリクエストになるのではなく、ここで 422 となります。
レスポンス
GET /v2/models/{provider}/{model}/requests/{request_id}
送信済みリクエスト1件の結果を収集します。
収集エンドポイントです。正常に完了したリクエストでは、パートナーモデル自身のネイティブ出力を返します。これは、同じモデルと同じ入力に対して同期ルートの 200 が返すものとバイト単位で同一です。そのため、2つの配信モードは1つの結果形状を生成し、呼び出し元は2つ目のパーサーなしでそれらの間を行き来できます。
パラメータ
レスポンス
PUT /v2/models/{provider}/{model}/requests/{request_id}/cancel
送信済みのリクエスト1件にキャンセルを要求します。
まだ完了していないリクエストを停止するよう Comfy に要求します。これは要求であり、保証ではありません。202 が示しているのはまさにそのとおりで、CANCELLATION_REQUESTED は要求が受理されたことを意味するだけで、実行が停止したことを意味するものではありません。すでにパートナー側へ送出された実行はそのまま完了してしまう可能性があります。そして完了したパートナー生成は、誰かが結果を取得したかどうかに関わらず課金されます。そのため、実際に何が起きたかを知る必要がある呼び出し元は、後からステータスエンドポイントを参照します。そこでは、実際に有効になったキャンセルは、他のあらゆるターミナルな結果と同様に error_type を伴う COMPLETED になります。
パラメータ
レスポンス
GET /v2/models/{provider}/{model}/requests/{request_id}/status
送信済みの1件のリクエストのキュー状態を読み取ります。
ポーリング用のエンドポイントです。リクエストの現在の状態のみを返し、結果は返しません。そのためクライアントは、ポーリングのたびに出力を転送することなく、長時間かかる生成を監視できます。結果は、これが COMPLETED を返したときに、後述の読み取りエンドポイントから一度だけ取得します。
パラメータ
レスポンス
表の説明は簡潔です。モデルの選択、検証、再試行、課金については Comfy Router API の使用 を、ヘッダーの動作については ヘッダー を参照してください。
エラーバケット
Router の機械可読なエラーカテゴリで、X-Comfy-Error-Type ヘッダーでも送信されます。
リクエストレベルバケット
Router が受け付けたものの、完了できなかったリクエストに対して発生します。トランスポートレベルバケット
モデルへの呼び出しの前またはその周辺で、Router 自身によって発生します。レスポンスヘッダー
結果アセット
モデルは、アセット URL、インラインバイト、またはその両方を返すことができます。以下のプロバイダーは、選択済みのアセットを Comfy ストレージにコピーし、その URL を置き換えます。この動作はモデルによって異なります。これを選択するリクエストヘッダーはありません。
これらの有効期間は、URL を開いたときではなく、URL が署名されたときに開始されます。キャッシュされた URL や再生された URL は残り時間が短い場合があります。再生しても有効期間は更新されません。アセットは速やかにダウンロードしてください。コピーされるのは各行に記載されたアセットのみです。
byteplus/seedream-* と byteplus/seededit-* の画像は BytePlus ビデオの行には含まれません。
Veo (veo/*) には別のストレージパスがあります。 response.videos[] では、存在する方のメンバーを読み取ってください。bytesBase64Encoded はクリップをインラインで含み、gcsUri は、プロバイダーから Comfy ストレージへの直接書き込みが環境で構成されている場合に、Comfy が署名した HTTPS リンクを含みます。そのリンクはレスポンスから 24 時間有効です。後者の場合はアセットをコピーするのではなく直接書き込むため、Veo は再ホスティングの表には含まれていません。
その他のモデルは、プロバイダーのアセット参照またはインラインバイトを返します。プロバイダーの URL はプロバイダーの有効期限に従います。これは上記の有効期間よりはるかに短い場合があり、Router の契約では規定されていません。
コピーはアセットごとのベストエフォートです。1 つのコピーが失敗した場合、そのエントリはプロバイダーの参照を保持します。レスポンスには Comfy とプロバイダーの両方の URL が含まれる可能性があり、アセットごとの明示的なコピーステータスフィールドはありません。生成は引き続き成功し、課金されます。1 つの正常に再ホストされたアセットから、すべての URL の有効期間を推測しないでください。
結果が Comfy ホストかどうかは、完了した呼び出しが後でその Idempotency-Key レコードから再生できるかどうかも決定します。上記の Idempotency-Key パラメーターは、再生できない場合に再試行が何で応答されるかを説明しています。
モデルごとの入力および出力スキーマ
各モデルのフィールドはGET /v2/models/{provider}/{model}/openapi.json から読み取ります。オペレーションの requestBody は入力の検証を記述しており、その 200 レスポンスは、スキーマが作成されている場合に出力の形状とメディアタイプを記述しています。x-comfy-input-schema-authored が false の場合、Router はモデル固有の事前検証なしで任意の JSON オブジェクトを受け入れます。プロバイダーの要件は引き続き適用されます。出力スキーマは結果を記述するものであり、Router は返されたプロバイダーのペイロードをそれらに対して検証しません。スキーマが作成されていない出力では、application/json ではなく */* が使用される場合があります。デコードする前にレスポンスのコンテンツタイプを確認してください。
スキーマ
RouterChargesOnPolicyRejection
このモデルでコンテンツポリシーによる拒否が課金されるかどうか。不明な値は課金される可能性があるものとして扱ってください。 型:string
RouterErrorResponse
認証、アクセス、モデル検索、クォータ、およびプロバイダー転送の失敗に対するエラーボディ。RouterErrorType
機械可読な Router エラーのカテゴリ。X-Comfy-Error-Type ヘッダーでも送信されます。
型: string
RouterModelBilling
モデルを呼び出す前に確認すべき課金の挙動。価格や使用量は含まれません。RouterModelDetail
1つの Comfy Router モデルに対するモデル単位の詳細です。カタログ一覧が報告するすべての内容に加えて、単一モデルルートだけが持つモデル単位のフィールドを含みます。RouterModelListEntry、RouterModelDetailFields を組み合わせます。
型: object
RouterModelDetailFields
モデル詳細エンドポイントが返すオプションフィールド。RouterModelId
POST /v2/models/{provider}/{model} で使用されるモデル ID。
型: 文字列。モデル ID(例: anthropic/claude-opus-4-6)、最大 193 文字
RouterModelInput
モデル入力オブジェクト。フィールドと検証については、選択済みモデルの OpenAPI ドキュメントを参照してください。 型:object
RouterModelInputSchemaDocument
1つのモデルの入力と出力に対応するスタンドアロンの OpenAPI ドキュメント。 型:object
RouterModelListEntry
モデルのIDと課金に関する事実。RouterModelListResponse
Router モデルカタログの 1 ページです。RouterModelOutput
モデルの結果オブジェクトです。正確な形状については、選択済みモデルの出力スキーマを参照してください。 型:object
RouterModelSegment
{provider}/{model} モデル ID のモデル部分です。
型: string。英数字のスラッグ(例: claude-opus-4-6)、最大 128 文字
RouterPageCursor
不透明なカタログカーソルです。変更を加えずにそのままcursor として渡し直してください。
型: string。next_cursor として返される不透明なカーソルで、1~512文字です。
RouterProviderSegment
{provider}/{model} というモデル ID のプロバイダー部分です。
型: string。英数字のスラッグ(例: anthropic)、最大 64 文字
RouterQueueCancelResponse
このルートが解決したリクエストを表す2つのステータス、すなわち202 と 400 に対するキャンセル要求への応答です。成功用のエンベロープとエラー用のエンベロープに分けるのではなく、両ステータスで単一のボディ形状をとります。どちらも「キャンセルで何が見つかったか」という同じ内容を伝えるものであり、ステータスコードごとに異なる型をパースしなければならないクライアントにとって、分割による利点は何もないからです。
RouterQueueCancelStatus
このルートが実際に解決したリクエストを表す2つの結果について、キャンセル要求が見つけた内容です。どちらも HTTP ステータスに反映されるため、クライアントはどちらで分岐してもかまいません。 型:文字列
RouterQueuePosition
レスポンスが構成された時点で、このリクエストより前にキュー内にあるリクエストの数。0 はこのリクエストが先頭であることを意味します。 型:integer — 0 以上
RouterQueueRequestId
キュー中の Router リクエスト 1 件の識別子。呼び出し元がポーリングやキャンセル、結果の取得に用いるハンドルです。 型:string、pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$、uuid、最大 36 文字
RouterQueueStatus
キュー中の Router リクエストの状態。値はちょうど 3 つで、RouterErrorType とは異なり、これは閉じた enum です。2 つのスキーマは意図的に逆方向に閉じられているためです。RouterErrorType は失敗を分類するもので、その集合は増えていくことが想定されているため、認識できないバケットをハード拒否する生成済みクライアントは、すでに何かが失敗したまさにその時に最も激しく失敗することになります。一方これはライフサイクルであり、後で 4 つ目の状態が追加されたライフサイクルは、enum として宣言されているかどうかに関わらず、それに対して書かれたすべてのポーリングループにとって破壊的変更となります。そのため enum として宣言され、その制約はクライアントが見られる場所に明記されています。
Type: string
RouterQueueStatusFields
RouterQueueStatusResponse のうち URL ブロックではない半分です。キュー中のリクエスト 1 件の識別情報、その現在の状態、そしてその状態がターミナルで実行が成功しなかった場合は、その理由を示す粗い分類を表します。
RouterQueueStatusResponse
キュー中のリクエスト1件の現在の状態を、送信時に返されたものと同じ3つのURLと組み合わせたものです。RouterQueueUrls、RouterQueueStatusFields を構成要素とします。
型: object
RouterQueueSubmitFields
RouterQueueSubmitResponse のうち URL ブロックではない半分: 新しいリクエストの識別情報と、それが受け付けられた時点での状態です。
RouterQueueSubmitResponse
実行がキューに受け入れられたときに返されるハンドルです。リクエストの識別情報と状態を、そのライフサイクルの残りの部分を指す 3 つの URL と合成したものです。RouterQueueUrls、RouterQueueSubmitFields を合成します。
型: object
RouterQueueUrls
キュー中の1つのリクエストの残りのライフタイムに対応する3つのURLです。有効なハンドルを含むすべてのレスポンスで返されるため、クライアントが自分でキューURLを組み立てることはありません。RouterValidationErrorContext
失敗した検証ルールに関するプロバイダー提供の詳細。 型:object
RouterValidationErrorDetail
1 件のフィールドレベルの検証失敗。RouterValidationErrorInput
プロバイダーが含めた場合の、拒否された入力値です。RouterValidationErrorResponse
422 検証エラーのレスポンスボディ。そのカテゴリについては X-Comfy-Error-Type を参照してください。