https://api.comfy.org
以下のすべてのエンドポイントは認証が必要です。Authorization: Bearer <jwt> を送信してください。
エンドポイント
GET /v1/models
Comfy Router が実行できるモデルを一覧表示します。
Comfy Router のモデルカタログ。POST /v1/models/{provider}/{model} が受け付ける正規モデル ID の 1 ページ分です。SDK はコールドスタート時にこの API を呼び出して実行可能なモデルを検出し、model_not_found の提案も同じカタログから取得されます。したがって、ここに掲載されている ID が呼び出し時に 404 になる場合は、どちらか一方の失敗だけよりも悪い結果になります。この一致は約束ではなく構造上のものです。エントリの provider と model は、呼び出しルートの2つのパスセグメントであり、そのルートのパスパラメータと同じスキーマコンポーネントを参照します。また、id はそれらの2つのセグメントを / で連結したものです。
パラメータ
レスポンス
正規のモデル ID で、パートナーモデルのカタログエントリを 1 件読み取ります。
単一の Comfy Router モデルに対するモデル単位の詳細です。呼び出し元は、ページ分割されたカタログ全体を走査しなくても、1 つのモデルを確認できます。SDK はモデルを呼び出す直前に、このエンドポイントを使用してモデルを検索します。
パラメータ
レスポンス
正規モデルIDでパートナーモデルを同期的に実行します。
Comfy Routerの正規のエントリポイントであり、モデルIDでアドレス指定されます。リクエストボディはパートナーモデル自身のネイティブなJSON入力であり、成功レスポンスはそのモデル自身のネイティブなJSON出力です。RouterはComfy形式のエンベロープを押し付けるのではなく、両方をそのまま転送するため、呼び出し元はホストを変更するだけでパートナーのAPIとRouterを切り替えることができます。これは同期パスであり、
POST https://fal.run/{id} をミラーリングします。レスポンスには完了した結果が含まれます。キュー処理用の対応エンドポイントである /v1/queue/models/{provider}/{model} が計画されており、falの fal.run と queue.fal.run の分割を単一のホストにまとめることになります。ただし、これはまだこの契約の一部ではありません。
パラメータ
リクエストボディ
application/json - RouterModelInput（必須）
パートナーモデルのネイティブなJSON入力で、プロバイダーにそのまま転送されます。
レスポンス
1つのパートナーモデルの入力スキーマをOpenAPIドキュメントとして読み取ります。
単一のComfy Routerモデルのモデルごとの入力スキーマは、スタンドアロンのOpenAPIドキュメントとして提供されます。これにより、呼び出し側（SDK、コード生成ツール、またはエージェント）は、Comfyの解説ドキュメントを読まなくてもモデルの引数を発見できます。これはfalのモデルごとのスキーマエンドポイントを反映したものであり、SDKクイックスタートが依存する発見メカニズムです。
パラメータ
レスポンス
エラーバケット
Router の失敗を示す、粗い粒度の機械可読バケットです。X-Comfy-Error-Type レスポンスヘッダーにもミラーリングされるため、呼び出し側はボディを解析せずに分岐できます。セットは15個の値で固定されています。リクエストレベルの6つのバケット invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits、model_not_found に加え、トランスポートレベルの unauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable、rate_limited です。
リクエストレベルバケット
Router が受け付けたものの完了できなかったリクエストに対して発生します。トランスポートレベルバケット
モデルへの呼び出しの前またはその周辺で、Router 自身によって発生します。レスポンスヘッダー
モデルごとの入力スキーマ
モデル独自の入力フィールドはここでは再掲しません。それらはGET /v1/models/{provider}/{model}/openapi.json から直接取得できます。このエンドポイントは、サーバーが呼び出しの検証に使用するのと同じドキュメントを提供するため、公開されている内容と実際に適用される内容が乖離することはありません。GET /v1/models からモデルIDを取得し、その呼び出しパスに /openapi.json を追加して、返されたドキュメントに基づいて生成します。
スキーマ
RouterChargesOnPolicyRejection
このモデルがコンテンツポリシー上の理由で拒否する呼び出しが、それでも呼び出し元に課金されるかどうか。プロバイダーによって異なり、その違いは呼び出し時に判別できません。同じ呼び出しでエラーと課金の両方を目にしたユーザーには、事前にそれを知る手段がありません。そのため、プロバイダーごとの暗黙の了解に委ねるのではなく、呼び出しの前にモデルごとに明記されています。 型:string### RouterErrorResponse
Routerのリクエストレベルのエラーボディ: リクエストがモデルに到達しなかった場合、またはモデル自身が報告しなかった理由(認証、クォータ、不明なモデルID、プロバイダーのトランスポート)で失敗した場合に返されるものです。モデルレベルの検証失敗には独自の形状RouterValidationErrorResponseがあります。FastAPIのdetail[]配列をこのdetail文字列に平坦化すると、SDKが分岐の判断に使用するフィールド単位の粒度が失われるためです。
Router障害の大まかで機械可読なバケットであり、
X-Comfy-Error-Type レスポンスヘッダーにもミラーリングされるため、呼び出し元はボディを解析せずに分岐できます。このセットは15個の値に限定されており、リクエストレベルの6つのバケット（invalid_input、content_policy_violation、provider_error、provider_timeout、insufficient_credits、model_not_found）と、トランスポートレベルのunauthorized、forbidden、concurrency_limit_exceeded、client_disconnected、internal_error、deadline_exceeded、not_enabled、service_unavailable、rate_limitedです。
型: string### RouterModelBilling
呼び出し前に呼び出し元が把握しておくべき、価格ではなくモデル単位の課金に関する事実です。利用量やコストの数値がここに記載されることはありません。
1つのComfy Routerモデルに関するモデルごとの詳細。カタログ一覧で示されるすべての情報に加え、単一モデルルートのみが保持するモデルごとのフィールドを含みます。
RouterModelListEntry と RouterModelDetailFields で構成されます。
型:object### RouterModelDetailFields
カタログ一覧が保持しない RouterModelDetail の半分: モデルごとのフィールドで、1回の参照には値するものの、ページ分割されたカタログページのすべてのエントリで繰り返すほどではないものです。
正規の Comfy Router モデル ID です。
{provider}/{model} は、POST /v1/models/{provider}/{model} でモデルを指定する際に使用する正確な値です。そのため、呼び出し元はこの値をそのままパスに埋め込むことができ、他の情報から再導出する必要はありません。pattern は RouterProviderSegment と RouterModelSegment を単一の / で連結したもので、maxLength はそれらの合計にそのセパレータを加えた長さです。
型: string、pattern: ^[a-z0-9]+([._-][a-z0-9]+)*/[a-z0-9]+([._-][a-z0-9]+)*$、maxLength: 193### RouterModelInput
パートナーモデルのネイティブな JSON 入力ドキュメントで、プロバイダーにそのまま転送されます。具体的な形状は Comfy ではなくパートナーが所有するため、これはオープンオブジェクトです。Router はフィールドを絞り込んだり、名前を変更したり、再ラップしたりしません。これは名前付きコンポーネントです（インラインの無名オブジェクトにはなりません）。ComfyUI の仕様駆動のコード生成では、生成対象のクラスが必要だからです。
型: object### RouterModelInputSchemaDocument
単一の Comfy Router モデルの入力を説明するスタンドアロンの OpenAPI ドキュメントです。これは、そのモデルに対して POST /v1/models/{provider}/{model} が受け付けるボディです。GET /v1/models/{provider}/{model}/openapi.json が返すのはこのドキュメントです。
型: object### RouterModelListEntry
Routerモデルカタログの1エントリです。実行可能なモデルの識別情報であり、それ以外の何ものでもありません。モデルごとの詳細ルートは、この同じエントリを再掲するのではなく合成するため、名前は...Summaryではなく...ListEntryとなっています。カタログエントリの定義は正確に1つだけ存在する必要があります。モデルごとの詳細と、モデルごとの入出力スキーマはそれぞれ独自のルートであるため、この形状は、呼び出し元がモデルを呼び出すために必要な最小限のものに留まっています。これは意図的なものであり、SDKがコールドスタート時に取得するペイロードだからです。idはproviderとmodelを/で連結したものです。この2つのフィールドは個別にも保持されるため、呼び出し元は文字列を分割することなく呼び出しパスを構成できます。
Routerモデルカタログの1ページ。
パートナーモデルのネイティブなJSON出力ドキュメントであり、呼び出し元にそのまま返されます。その具体的な形状はComfyではなくパートナーが所有しているため、これはオープンなオブジェクトです。Routerはフィールドの絞り込み、名前の変更、再ラップを行いません。これは名前付きコンポーネントです（インラインの匿名オブジェクトではありません）。ComfyUIのスペック駆動のコード生成では、生成対象のクラスが必要になるためです。
型:
object### RouterModelSegment
正規の {provider}/{model}[/{variant}] モデル ID の小文字の model セグメント。そのプロバイダー内で実行するモデルを指します。RouterProviderSegment と同じくドリフトを防ぐため、呼び出しルートの model パスパラメータとカタログエントリの model フィールドで共有されます。
型: 文字列。pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$、maxLength: 128### RouterPageCursor
Router リストに対する不透明なカーソルです。これはサーバーによって生成され、常にラウンドトリップされるだけです。オフセットでもなく、モデルIDでもなく、順序付けもされておらず、カタログの再構築をまたいでも安定しません。そのため、カーソルを解析したり、インクリメントしたり、導出元となった走査を超えて永続化したりすることは、すべて契約の範囲外です。カタログが変動するリストであるため、オフセットではなくカーソルが採用されています。オフセットによる走査では、走査の途中でエントリが追加または削除されると、エントリが暗黙的にスキップまたは繰り返され、呼び出し側はその発生を検知できません。
型: string — pattern: ^[A-Za-z0-9._~+/=-]+$, minLength: 1, maxLength: 512### RouterProviderSegment
標準の {provider}/{model}[/{variant}] モデルIDの小文字の provider セグメント。これは、モデルがアドレス指定されるパートナーを示します。呼び出しルートの provider パスパラメータとカタログエントリの provider フィールドは、どちらもこの単一のスキーマを参照します。これにより、リストされたIDと受け入れられるIDが乖離するのを防ぎます。
型: string。pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$、maxLength: 64### RouterValidationErrorContext
1つの RouterValidationErrorDetail に対する違反されたバウンドで、プロバイダーからそのまま引き継がれます。例えば、greater_than に付随する {"limit_value": 8}、image_too_small に付随する {"min_width": 512}、file_too_large に付随する {"max_size_bytes": 10485760} などです。キーのセットはプロバイダーとエラータイプに固有であるため、これは意図的にオープンなオブジェクトです。固定のフィールドリストに絞り込んだり、msg 文字列に折り込んだりすることは、移植されたインテグレーションがコンパイルされ、バウンドを読み取るブランチを静かに失う、まさにその方法です。エラータイプがバウンドを持たない場合は存在しません。
型: object### RouterValidationErrorDetail
fal/FastAPI 形式のモデルレベルの検証エラー 1 件分です。type は、RouterErrorType の粗いバケットでは表現できない粒度である、プロバイダー固有の具体的な理由（value_error、missing、image_too_small、unsupported_audio_format、greater_than、file_too_large など）を保持します。同じ理由で、これはオープンな文字列であり、enum ではありません。プロバイダーの語彙は 2 つの層にわたって約 48 の値に上り、当社ではなくプロバイダーのリリースサイクルに応じて増えていきます。モデル化されていない値は、デシリアライゼーションに失敗するのではなく、呼び出し元に届かなければなりません。
拒否された入力値をそのままエコーバックしたものです。呼び出し元は
loc から値を再導出しなくても、何が拒否されたかを確認できます。値はあらゆるJSON型（文字列、数値、ブール、配列、オブジェクト、null）を取り得るため、このスキーマはオブジェクトに限定せず、意図的に型指定なしとしています。プロバイダーが入力をエコーバックしない場合、このフィールドは存在しません。### RouterValidationErrorResponse
Routerのモデルレベルの422ボディ（fal/FastAPI形式）：リクエストはモデルに到達するのに十分な形式であり、モデルがその内容を拒否したことを示します。これ自体にはerror_typeが含まれないことに注意してください。その役割はレスポンスのX-Comfy-Error-Typeヘッダーが担うため、クライアントは2種類のRouterエラーボディのどちらを受信したかを先に判断することなく、ヘッダーから大まかな分類を読み取ることができます。