ComfyUI APIの使い方｜API v2・Cloud API・Server APIの違いから理解する

ComfyUIを画面以外から動かす経路は、自分のPCで動く「ComfyUI Server API」、公式SDK付きでバージョン管理される「Comfy API v2」、Comfy Cloud専用の「Cloud API」の三つです。どれも「API形式のworkflow JSONを送り、Queueに入れ、結果を取りに行く」という同じ流れで動きます。三経路の違い、全体像、ローカルServer APIでの最小実行、Cloudとローカルの差分を整理します。

情報確認日：2026年8月22日（日本時間）

結論：ローカルで試すならServer API、長く使う統合ならAPI v2＋SDK

ComfyUIにはどのAPI経路があるか

公式ドキュメント（2026年8月時点）は外部からComfyUIを動かす方法を三つに分けています。「どこで実行されるか」と「互換性の約束があるか」で区別します。

Server APIは8188番で動く普段のComfyUIそのもので、UIが内部で使う経路と同じです。API v2はローカルでも8189番のプロキシ経由で同じ形で呼べるため、「最初はローカル、あとでCloud」がURL差し替えで済む設計です。

WorkflowをAPI実行する全体像

経路が違っても、やることは同じ四段階です。出発点はどれも「GUIで動いたworkflowをAPI形式へ出す」ことです。

1. 1
   API形式のJSONを用意する

   現行UIのFile → Export Workflow (API)で書き出す。GUI保存用JSONとは構造が違う

2. 2
   送信する

   Server APIならPOST /prompt、API v2ならPOST /api/v2/jobsにJSONを入れて送る

3. 3
   Queueで待つ

   返ってきたprompt_id（v2ではjob id）を手がかりに、完了をポーリングかWebSocket／SSEで待つ

4. 4
   結果を取りに行く

   Server APIは/history/{prompt_id}で出力ファイル名を知り、/viewで取得。v2はjobのoutputsからアセットURLをたどる

GUI用JSONとAPI形式JSONの構造差は別記事で扱います。ここでは「GUI保存のJSONをそのまま送ると動かない」ことだけ押さえてください。API v2は、UI形式を送るとworkflow_format_uiという理由で拒否すると公式に明記しています。

ローカルServer APIの基本

Server APIは起動中のComfyUIがすでに提供しているHTTPルートで、追加インストールは不要です。公式のルート一覧（2026年8月22日確認）の主なものを挙げます。

動作確認として次を実行し、JSONが返ればAPIとして話せる状態です。

# 2026-08-22 に公式ルート一覧で確認したエンドポイント
curl http://127.0.0.1:8188/system_stats
curl http://127.0.0.1:8188/object_info -o object_info.json

/object_infoは、書き換える入力名に迷ったときの辞書です。保存したファイルをKSamplerで検索すれば、seed・steps・cfgの入力名をUIを開かずに確かめられます。

API v2・SDKを使う場面

「一度書いたコードを、更新やCloud移行をまたいで動かし続けたい」ならAPI v2とSDKが候補です。公式は新規統合にこの経路を推奨しています。

• Server API：追加導入なしで8188番へ直接HTTP。Queue操作やノード定義まで全機能に触れるが、更新で壊れたら自分で追従する
• API v2＋SDK：pip install comfy-sdk／npm i @comfyorg/sdk。ローカルは8189番のプロキシ経由で、ベースURLの差し替えでCloudへ移れる。Beta（0.1.x）で、workflow管理やノード定義の取得は現時点で対象外

v2の設計原則として公式は「Poll first」を掲げています。すべての機能はGET /api/v2/jobs/{id}のポーリングで到達でき、SSEストリームは補助という位置づけです。jobのstatusはqueued → running → succeeded | failed | expiredと遷移し、outputsには実行中から順次アセットが入ります。

SDKの導入と入力差し替え、出力保存はPython・TypeScriptそれぞれの記事で扱います。ここでは「SDKはServer APIの薄いラッパーではなく、v2という別経路を包んでいる」ことだけ覚えてください。

Cloudとローカルを混同しない

cloud.comfy.orgにはAPI v2とCloud APIの両方があり、SDKもCloudを既定にしています。ローカルのつもりでCloudを叩く事故を防ぐため、次を分けて確認します。

SDKのサンプルはapi_keyを渡す形で始まるため、ローカルで使うときはベースURLをhttp://127.0.0.1:8189へ明示します。「Server APIの8188とv2の8189は別物」です。Server APIをLANや外部へ公開するときの認証・TLS・リバースプロキシは別記事で扱います。

最小APIサンプル：Promptだけ差し替えて1枚生成する

GUIで動くことを確認済みのworkflowを使い、Server APIで正のPromptだけ変えて1枚生成します。公式リポジトリのscript_examples/basic_api_example.pyと同じ考え方です。

手順

1. GUIでいつものworkflowを1回実行し、生成できることを確認する
2. File → Export Workflow (API)でworkflow_api.jsonを保存する（現行UI、2026年8月時点）
3. JSONを開き、正のPromptを持つCLIPTextEncodeノードのキー（数字）を控える
4. 下のスクリプトのノードキーを自分のものに合わせて実行する
5. outputフォルダの新しい画像と/historyのレスポンスを確認する

# 確認日: 2026-08-22 / 公式 script_examples/basic_api_example.py と
# comms_routes のルート一覧に基づく。ComfyUI を 127.0.0.1:8188 で起動済みの前提。
import json
import time
from urllib import request

SERVER = "http://127.0.0.1:8188"
POSITIVE_NODE = "6"  # 自分の workflow_api.json で正の Prompt を持つノードのキー

with open("workflow_api.json", encoding="utf-8") as f:
    prompt = json.load(f)

prompt[POSITIVE_NODE]["inputs"]["text"] = "a quiet harbor at dawn, watercolor"

body = json.dumps({"prompt": prompt}).encode("utf-8")
req = request.Request(f"{SERVER}/prompt", data=body,
                      headers={"Content-Type": "application/json"})
with request.urlopen(req) as res:
    prompt_id = json.load(res)["prompt_id"]
print("queued:", prompt_id)

while True:
    with request.urlopen(f"{SERVER}/history/{prompt_id}") as res:
        history = json.load(res)
    if prompt_id in history:
        break
    time.sleep(1)

for node_id, output in history[prompt_id]["outputs"].items():
    for image in output.get("images", []):
        print(node_id, image["filename"], image["subfolder"], image["type"])

表示されたfilename・subfolder・typeをそのまま/viewのクエリに渡せば画像本体を取得できます。

curl "http://127.0.0.1:8188/view?filename=ComfyUI_00001_.png&subfolder=&type=output" -o result.png

何を見て成功と判断するか

• POST /promptのレスポンスにprompt_idがある。入力名の誤りはこの段階でエラーとして返る
• /history/{prompt_id}がoutputsを持つ。完了前はキー自体が存在しない
• GUIのQueueパネルにも同じ実行が現れる。UIとAPIは同じQueueを共有している

ポーリングではなく/wsのexecuting通知で完了を待つ方法は別記事で扱います。

よくある質問

まとめ

ComfyUIのAPI経路はServer API、API v2、Cloud APIの三つで、「API形式JSONを送り、Queueを待ち、結果を取りに行く」流れは共通です。違うのは実行場所・認証・互換性の約束です。

最初の一歩は、GUIで動くworkflowをFile → Export Workflow (API)で書き出し、/promptへ送って/historyで確認することです。workflow JSONそのものの扱いはComfyUIのworkflow JSONを読み込む方法を参照してください。