Comfy SDK

ベータ。 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セットです。

インストール

pip install comfy-sdk

npm i @comfyorg/sdk

Python 3.10 以降。Node 22 以降。

クイックスタート

入力画像をアップロードし、ワークフローを実行して、結果をディスクに書き込みます。

from comfy_sdk import Comfy

# Comfy Cloud
client = Comfy(api_key="comfyui-...")

wf = client.workflows.from_file("workflow_api.json")

asset = client.assets.from_file("photo.png")
wf.set_input("10", "image", asset)

job = client.run(wf)
for output in job.get_outputs("9"):
    output.to_file(output.name)

import { Comfy } from "@comfyorg/sdk";

// Comfy Cloud
const client = new Comfy({ apiKey: "comfyui-..." });

const wf = await client.workflows.fromFile("workflow_api.json");

const asset = client.assets.fromFile("photo.png");
wf.setInput("10", "image", asset);

const job = await client.run(wf);
await job.getOutputs("9")[0].toFile("out.png");

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

ベースURLの選択

接続先	Base URL	APIキー
Comfy Cloud	`https://cloud.comfy.org` (デフォルト)	必須
サーバーレスデプロイ	`https://<deployment>.run.comfy.app`	必須
ご自身のComfyUI	`http://127.0.0.1:8189` (ローカルプロキシ)	デフォルトでは不要。オプションの静的ベアラートークン

ベースURLはコンストラクタ引数ではなく、COMFY_BASE_URL環境変数から取得されます:

export COMFY_BASE_URL="https://<deployment>.run.comfy.app"  # serverless
export COMFY_BASE_URL="http://127.0.0.1:8189"               # self-hosted proxy

この変数はクライアントが構築されるたびに読み取られ、http(s) URLである必要があります。未設定または空白の場合はComfy Cloudを意味します。したがって、クライアント自体はどこでも同じです:

client = Comfy(api_key="comfyui-...")

const client = new Comfy({ apiKey: "comfyui-..." });

初期ビルドからアップグレードしますか? Comfy("<url>", "<key>")は、COMFY_BASE_URLを設定したComfy(api_key="<key>")になりました。api_keyはキーワード専用引数なので、以前の位置引数での呼び出しは、URLをキーとして静かに読み取るのではなく、TypeErrorを発生させます。

Comfy Cloud

そのまま動作します。APIキーを作成し、クライアントに渡します。

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

サーバーレスデプロイ

開発者プラットフォームを通じてデプロイしたワークフローには、専用のエンドポイントが割り当てられます。COMFY_BASE_URLをそのエンドポイントに指定し、Comfy Cloudとまったく同じようにAPIキーを使用します。このガイドのすべてが同じように機能します。サーバーレスデプロイはピン留めされた1つのワークフローを実行するため、get_workflow()は実行されたグラフ（format: "api"）を返します。

ご自身のComfyUI

ベータ期間中、v2 APIはcomfy-api-proxyによって提供されます。これは、ComfyUIと一緒に動作する小規模なオープンソースサービスです。

pip install comfy-api-proxy
comfy-api-proxy

デフォルトでは、127.0.0.1:8188のComfyUIをプロキシし、127.0.0.1:8189でv2 APIを提供します。いずれかを変更するには、--comfyuiと--portを使用します。次に、COMFY_BASE_URL="http://127.0.0.1:8189"を設定します。認証はデフォルトでは不要です。プロキシに静的ベアラートークンを設定している場合は、そのトークンをSDKのAPIキーとして渡します: Comfy(api_key="...")。プロキシはデフォルトではループバックにのみバインドします。インストール環境にモデルファイルもアップロードしたい場合は、--comfyui-base-dir /path/to/ComfyUIを指定して実行してください。プロキシは暫定対策です。v2 APIが安定すれば、ComfyUIコアに組み込まれ、プロキシは不要になります。

ジョブの実行を監視する

job.events() は、ジョブの状態のライブストリームを提供します。ノードとステップの進捗、プレビューフレーム、各出力がコミットされた瞬間のデータを取得できます。接続が切断された場合は、自動的に再接続されます。

from comfy_sdk import Progress, Preview, OutputReady, StatusChange

job = client.submit(wf)

for event in job.events():
    match event:
        case Progress() as p:
            print(f"{p.value:.0%} {p.message}")
        case Preview() as pv:
            image = pv.to_pil()
        case OutputReady() as o:
            o.output.to_file(f"partial/{o.output.name}")
        case StatusChange(status="succeeded"):
            break

result = job.result()

const job = await client.submit(wf);

for await (const event of job.events()) {
  switch (event.kind) {
    case "progress":
      console.log(event.value);
      break;
    case "outputReady":
      await event.output.toFile(`${event.output.name}`);
      break;
    case "statusChange":
      if (event.status === "succeeded") break;
  }
}

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

出力を生成元のワークフローまで遡る

出力には、それを生成したジョブのIDが保持されています。そのため、サイドテーブルを保持しなくても、ファイルから逆方向に遡ることができます。

output = job.outputs[0]
output.job_id          # the job that produced this file

const output = job.outputs[0];
output.jobId; // the job that produced this file

同じIDは、単体で取得したアセットにも付いています。後で見つけたファイルでも、そのジョブまで遡れます。アップロードしたアセットには生成元のジョブがないため、この値はNone（TypeScriptではundefined）になります。ジョブから、その背後にあるワークフローを取得できます。これは、このプロセス内で送信したものではなく、IDで再水和されたジョブでも機能します。

wf = job.get_workflow()

if wf.format == "save":
    ...  # the workflow as authored, canvas layout and Note nodes intact
else:
    ...  # the executed API-format graph

const wf = await job.getWorkflow();

if (wf.format === "save") {
  // the workflow as authored, canvas layout and Note nodes intact
} else {
  // the executed API-format graph
}

常にformatで分岐してください。 返ってくる形状は、ジョブがどのように送信されたかによって決まり、リクエストごとに制御できるものではありません。

`format`	取得できるもの	ケース
`save`	ジョブが実行されたバージョンの作成時ワークフロー。キャンバスレイアウトとNoteなどのエディタ専用ノードを含みます	Comfy Cloudエディタから送信されたジョブ。ワークフローバージョンが固定されています
`api`	実行されたグラフ。エディタ専用の構成要素は除去され、Get/Setノードは展開されています	その他すべて（今日これらのSDKを通じて送信されるすべてのジョブを含みます）

SDKを通じて送信したジョブは常にapiを返します。v2送信にはバージョン固定フィールドがまだないためです。この動作は将来変更されます。判別子が用意されているのは、コード側の変更が不要になるようにするためです。

SDK が現在対応している範囲

最初のバージョンは、1つのことをきちんと行います。ワークフローを実行して結果を取得することです。

アセット: ファイル、バイト、ストリーム、または URL から入力ハンドルを作成します。ハンドルは遅延評価され、コンテンツアドレス方式のため、同じ入力で再実行しても再アップロードされません。
送信: API 形式のグラフを送信します。送信は冪等であり、キューが満杯の場合も、限られた予算内で自動的に再試行されます。
実行: wait() でポーリングするか、events() でリアルタイムの進捗を追跡します。
出力: ディスクに書き込む、メモリにバッファリングする、バイト範囲を取得する、または短期間有効なダウンロード URL を取得します。
トレーサビリティ: すべての出力には、それを生成したジョブの ID が含まれ、ジョブからその背後にあるワークフローを取得することもできます。
アセットの削除: アップロードしたアセットを、ハンドルまたは ID で削除します。
エラー: 生のステータスコードではなく、JobFailed、Unauthorized、InsufficientCredits、QueueFull などの型付き例外。
キャンセル: 実行中のジョブをキャンセルできます。TypeScript では、任意の呼び出しで AbortSignal も受け付けます。

Python には、同期 Comfy クライアントと、同じインターフェースを持つ AsyncComfy クライアントの両方が用意されています。TypeScript は非同期のみです。このバージョンには含まれないもの: 保存したワークフローの管理、モデルライブラリ、ノードのイントロスペクション、名前付きワークフローパラメータ。設計ノートでは、なぜ API サーフェスがこのように小さく始まるのかを説明しています。

リファレンス

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と通信できますが、どこに需要があるのかを把握したいと考えています。

Comfy で開発する

ワークフローの実行

Comfy Router

Comfy CLI

仕様

インストール

クイックスタート

ベースURLの選択

Comfy Cloud

サーバーレスデプロイ

ご自身のComfyUI

ジョブの実行を監視する

出力を生成元のワークフローまで遡る

SDK が現在対応している範囲

リファレンス

Python SDK

TypeScript SDK

Comfy API v2 リファレンス

設計ノート

フィードバック

​インストール

​クイックスタート

​ベースURLの選択

​Comfy Cloud

​サーバーレスデプロイ

​ご自身のComfyUI

​ジョブの実行を監視する

​出力を生成元のワークフローまで遡る

​SDK が現在対応している範囲

​リファレンス

Python SDK

TypeScript SDK

Comfy API v2 リファレンス

設計ノート

​フィードバック

インストール

クイックスタート

ベースURLの選択

Comfy Cloud

サーバーレスデプロイ

ご自身のComfyUI

ジョブの実行を監視する

出力を生成元のワークフローまで遡る

SDK が現在対応している範囲

リファレンス

フィードバック