なぜ新しい API なのか
既に HTTP 経由で/prompt と /history を呼び出して ComfyUI を操作できます。これらのエンドポイントは ComfyUI の Web UI を支えるために存在しており、それらを基に構築することは、あなたに約束されていない内部実装に依存することを意味します。v2 API は、それらが提供できない 3 つのものを追加します。
確約。 v2 はバージョン管理され、ドキュメント化され、サポートされています。v2 内での変更は追加的なものです。破壊的な変更は v3 としてリリースされます。ComfyUI の新しいリリースによってあなたの統合が壊れることはありません。
移植性。 ローカルの ComfyUI に対しても、Comfy Cloud に対しても、後で提供する他の何に対しても、同じ動作を実現します。同じコードで、異なるベース URL です。
本番環境に耐える形状。 永続的なジョブ ID、冪等な送信、型付きエラー、正規化された出力、そして真のバックプレッシャーを備え、すべての統合が prompt_id と /history の上にこれら 5 つを再発明する必要はありません。
既存のエンドポイントをラップしない理由
それらは、一度に1つのワークフローを実行する単一のComfyUIインスタンスを前提としており、その前提がprompt_id、/history、およびWebSocketプロトコルに組み込まれているためです。
v2 APIはその前提を持ちません。同時に多数のワークフローが実行され、それぞれが永続的なジョブIDで識別されることが、例外ではなくデフォルトのケースです。
まずポーリング、進捗はストリームで
v2 のすべての機能は、通常の GET リクエストで利用できます。GET /api/v2/jobs/{id} は、現在のステータス、最新の進捗スナップショット、およびこれまでにコミットされたすべての出力を返します。これはジョブの正規のビューであり、ジョブの expires_at まで利用可能です。
GET /api/v2/jobs/{id}/events の SSE ストリームは、両 SDK で job.events() として公開されており、その上に構築されたライブ拡張機能です。プログレスバーを駆動するために使用してください。真実のソースとして使用しないでください。イベント ID はなく、再開カーソルもなく、切断されていた間に送信されたフレームは失われます。
正規の方法がストリームやウェブフックではなくポーリングである理由は 2 つあります。
- ワークフローは長時間実行される可能性があります。3 秒間接続が途切れても、結果を失うことは決してないはずです。
- ウェブフックは、公開アドレスを持つサービスには適しています。ポートで待ち受けていない個人のデスクトップ上の Blender プラグインには機能せず、また機能すべきでもありません。
GET /api/v2/jobs/{id} にはステータスと出力がまだあります。他のトランスポートは、それに適したケースのために後で追加される可能性があります。この方法はどこでも機能します。
既存APIとの関係
非推奨となるものはありません。/prompt、/history、/ws、およびその他のAPIは引き続き動作し、Cloud APIも動作し続けます。現在動作している統合は、これによって壊れることはありません。この2つは共存します。
最初のバージョンの範囲
ひとつのことをきちんと実現する: ワークフローを実行し、結果を取得する。入力をアップロードし、API形式のグラフを送信し、実行を監視し、出力を取得する。 これが意図的に設定された全体の範囲です。保存されたワークフロー、モデルライブラリ管理、ノードのイントロスペクション、名前付きワークフローパラメータはまだここにはありません。ComfyUIが展開されるあらゆる方法で確実にサポートできる小さな範囲を提供するほうが、一部の方法でしか機能しない大きな範囲を提供するよりも望ましいと考えています。ここから成長していきます。ローカルプロキシ
ベータ期間中、セルフホスト型ComfyUIはcomfy-api-proxyを介してv2で通信します。このプロキシはインスタンスと並行して実行され、その前面でv2コントラクトを提供します。これはオープンソースであり、あくまで一時しのぎの措置です。APIが安定化すると、これはComfyUIコアに組み込まれ、プロキシは不要になります。なぜPythonとTypeScriptが最初なのか
それは、すでにComfyUIをスケール環境で運用している人々に尋ねたところ、需要があったのがこの2言語だったからです。両SDKは同じ文書化されたHTTPコントラクトに基づいているため、どの言語でも今すぐAPIを利用できます。他の言語のファーストパーティSDKをご希望の場合は、当Discord の#developer-platform チャンネルでお知らせください。
私たちがあなたに求めていること
APIが0.1.xであるのには理由があります。今後数週間でAPIのインターフェースを固定する予定です。メソッド名、クライアントの形状、イベントカタログ、エラーの分類体系、そして実際のアセット処理の使用感は、今のうちならまだ簡単に変更できます。フィードバックを参照してください。