Skip to main content
ベータ。 SDKと、それらが呼び出すComfy API v2は0.1.xです。APIの形状は、確定する前にまだ変更される可能性があります。今が、間違っていることを私たちに伝えるのに最もコストのかからない時期です。フィードバックを参照してください。
Comfy SDKを使用すると、アプリケーションでComfyUIワークフローを実行し、結果を受け取ることができます。ワークフローを送信すると、ComfyUIがそれを実行し、出力をダウンロードできます。同じコードが、Comfy Cloudまたは自分でホストするComfyUIインスタンスに対して実行されます。変更されるのはベースURLのみです。 SDKは、Comfy API v2のクライアントです。これは、長期的にサポートする予定のバージョン管理されたHTTP APIです。ComfyUIの新しいリリースでも、それに基づいて構築された統合が壊れることはありません。 この方法で人々が構築するもの:
  • BlenderやKritaなど、別のアプリケーション内でコンテンツを生成するプラグイン
  • ユーザーに代わって生成を実行するコンシューマー向けアプリ
  • バッチパイプライン。たとえば、ビデオの全フレームに1つのワークフローを実行するなど
  • 同時に多くのワークフローを処理する必要があるバックエンドサービス
これらのSDKは、ComfyUIを外部から操作します。ComfyUIの内部で実行されるカスタムノードやフロントエンド拡張機能を記述している場合は、代わりにカスタムノードの開発を参照してください。これらは別のAPIセットです。

インストール

Python 3.10 以降。Node 22 以降。

クイックスタート

入力画像をアップロードし、ワークフローを実行して、結果をディスクに書き込みます。
workflow_api.json は、API 形式で保存されたワークフローです。"10""9" はそのファイル内のノード ID です。入力画像が送り込まれるノードと、結果を取得したい出力ノードを指します。 アセットハンドルは遅延評価されます。photo.png はローカルでハッシュ化され、サーバーがそのバイトをまだ保持していない場合にのみアップロードされます。そのため、同じ入力を使用して再実行してもコストはかかりません。 run() はジョブを送信し、ターミナル状態に達するまで待機します。実行中に他の作業を行うには、代わりに submit() を使用し、イベントストリームを監視してください。 代わりに自分の ComfyUI に対して実行するには、1行変更してキーを削除します: Comfy("http://127.0.0.1:8189")。以下を参照してください。

ベースURLの選択

Comfy Cloud

そのまま動作します。APIキーを作成し、クライアントに渡します。
APIアクセスには有料のComfy Cloudサブスクリプションが必要です。無料プランには含まれません。同時に実行できるジョブ数はプランによって異なります。Cloud API概要をご覧ください。

ご自身のComfyUI

ベータ期間中、v2 APIはcomfy-api-proxyによって提供されます。これは、ComfyUIと一緒に動作する小規模なオープンソースサービスです。
デフォルトでは、127.0.0.1:8188のComfyUIをプロキシし、127.0.0.1:8189でv2 APIを提供します。いずれかを変更するには、--comfyui--portを使用します。 その後、SDKをhttp://127.0.0.1:8189に指定します。認証はデフォルトでは不要です。プロキシに静的ベアラートークンを設定している場合は、同じトークンを SDK の API キーとして渡します: Comfy("http://127.0.0.1:8189", api_key="...")。プロキシはデフォルトではループバックのみにバインドします。インストール環境にモデルファイルもアップロードしたい場合は、--comfyui-base-dir /path/to/ComfyUIを指定して実行してください。 プロキシは暫定対策です。v2 APIが安定すれば、ComfyUIコアに組み込まれ、プロキシは不要になります。

ジョブの実行を監視する

job.events() は、ジョブの状態のライブストリームを提供します。ノードとステップの進捗、プレビューフレーム、各出力がコミットされた瞬間のデータを取得できます。接続が切断された場合は、自動的に再接続されます。
Preview.to_pil() にはオプションの Pillow extra が必要です: pip install "comfy-sdk[pil]" result() は、完了したジョブを返します。実行に失敗した場合は、ノードレベルの詳細情報を含む JobFailed を送出します。完全なイベントカタログについては、お使いの言語の SDK README を参照してください。 ストリームはライブフィードであり、再生可能なログではありません。進捗を表示するためのものであり、結果の取得に依存するためのものではありません。ジョブのポーリングこそが信頼できる情報源であり、run()wait()result() は自動的にポーリングにフォールバックします。理由については、設計ノート を参照してください。

現在SDKがカバーするもの

最初のバージョンは、1つのことを適切に行います: ワークフローを実行して結果を取得することです。
  • アセット。 ファイル、バイト、ストリーム、またはURLから入力ハンドルを作成します。ハンドルは遅延評価され、コンテンツアドレス方式であるため、同じ入力で再実行しても再アップロードされません。
  • 送信。 API形式のグラフを送信します。送信は冪等であり、キューがいっぱいの場合は、制限された予算内で自動的に再試行されます。
  • 実行。 wait()でポーリングするか、events()でライブの進行状況を追跡します。
  • 出力。 ディスクに書き込んだり、メモリにバッファリングしたり、バイト範囲を取得したり、短期間有効なダウンロードURLを取得したりできます。
  • エラー。 生のステータスコードではなく、JobFailedUnauthorizedInsufficientCreditsQueueFullなどの型付き例外。
  • キャンセル。 実行中のジョブはキャンセルできます。TypeScriptでは、任意の呼び出しでAbortSignalも受け入れます。
Pythonには、同じサーフェスを持つ同期ComfyクライアントとAsyncComfyクライアントの両方が用意されています。TypeScriptは非同期のみです。 このバージョンに含まれないもの: 保存済みワークフローの管理、モデルライブラリ、ノードイントロスペクション、名前付きワークフローパラメータ。設計ノートでは、サーフェスがこれほど小さく始まる理由を説明しています。

リファレンス

SDK の README は、認証、アセット、エラー、低レベルのエスケープハッチなど、各言語の完全なリファレンスです。

Python SDK

comfy-sdk は PyPI で公開されています。同期クライアントと非同期クライアントに対応しています。

TypeScript SDK

@comfyorg/sdk は npm で公開されています。型付けされた非同期クライアントで、低レベルクライアントも備えています。

Comfy API v2 リファレンス

両 SDK の基盤となる HTTP API です。任意の言語から直接利用できます。

設計ノート

この API が存在する理由、既存の ComfyUI API との関連性、そして今後の展開について説明します。

フィードバック

あえて 0.1.x にしています。メソッド名、クライアントの形、イベントカタログ、エラーの分類体系、実際のアセット処理の使用感は、まだどれも変更が容易です。今後数週間のうちにインターフェースを固定する予定です。その後は、「長期的にサポートします」というのは、もはやあなたのために修正できないという意味になり始めます。 だから、使いにくい点、見つかると思っていたのに見つからなかった点、結局回避策を取らざるを得なかった点を教えてください。そのための場所は、私たちのDiscord#developer-platform チャンネルです。 別の言語向けのファーストパーティSDKが必要な場合は、そこでお知らせください。どちらのSDKも同じ文書化されたHTTPコントラクトに基づいているため、現在どの言語でもAPIと通信できますが、むしろ需要がどこにあるのかを知りたいのです。