ComfyUI API完全ガイド｜/promptエンドポイントの使い方

2026年4月20日

六波羅涼

ComfyUIをGUIだけで操作していると、大量の画像生成に時間がかかります。プログラムからComfyUI APIを呼び出せば、数百枚・数千枚の画像をバッチ処理で自動生成できます。

中核となるのが /prompt エンドポイントです。ワークフローのJSONをHTTP POSTで送信し、WebSocketで進捗を監視しながら結果を取得する流れが基本になります。

この記事では、ComfyUI APIの主要エンドポイントの役割から、PythonやNode.jsでの実装、extra_data 経由のAPI Key認証まで順を追って解説します。

体験カリキュラム

Blenderで作る
初めての建築3DCGパース

Blenderの導入から基本操作、太陽光の入る白い部屋の制作まで。全3本のカリキュラムを体験できます。

まずは体験カリキュラムを受講

ComfyUI APIの基本構成と主要エンドポイント

ComfyUIはローカルサーバーとして起動し、既定では http://127.0.0.1:8188 でAPIリクエストを受け付けます。プログラムから操作する場面で押さえておきたい主要なエンドポイントは5つです。

/promptエンドポイントの役割と仕組み

/prompt はComfyUI APIの中核です。ワークフローのJSON（API形式）をPOSTリクエストで送ると、そのワークフローが実行キューに追加されます。

リクエストの最小形は次のとおりです。

{
  "prompt": { ... },
  "client_id": "任意のUUID",
  "extra_data": { ... }
}

prompt フィールドにはワークフロー全体のJSON（API形式）を格納します。client_id はWebSocket接続で進捗を自クライアント宛にフィルタするための識別子です。extra_data は任意ですが、後述するAPI Node利用時にAPI Keyを渡す公式フィールドとして使います（2026年4月現在）。

送信が成功すると、レスポンスで prompt_id（ジョブの一意ID）と number（キュー内の順番）が返ります。バリデーションエラーがあれば error と node_errors が返るため、デバッグにも役立ちます。

/queue・/history・/view・/uploadの使い分け

残りの4つのエンドポイントは、ジョブ管理・結果取得・入力画像アップロードに使います。

エンドポイント	メソッド	用途
`/queue`	GET	実行中・待機中のジョブ一覧を取得
`/history/{prompt_id}`	GET	完了ジョブの出力ファイル情報を取得
`/view`	GET	生成画像をファイル名・サブフォルダ指定でダウンロード
`/upload/image`	POST	ワークフローで使う入力画像をアップロード（img2img・ControlNet等で必須）

/prompt でジョブを投入し、/history/{prompt_id} で完了を確認してから /view で画像を取得する流れが基本パターンです。/queue はデバッグ時にキューの詰まり具合を確認する用途で重宝します。

img2img や ControlNet のワークフローでは、LoadImageノードが参照する入力画像を事前に /upload/image へ multipart/form-data で送り、サーバー側の input フォルダに置く必要があります。アップロードできた画像名をワークフロー側のLoadImage入力に差し込めば、API経由のimg2imgが成立します。

ワークフローJSONをAPI形式に変換する方法

ComfyUIのGUIで作ったワークフローを、そのままAPIに送信できるのでしょうか。実は、API専用の形式に変換する必要があります。

手順は3ステップです（2026年4月現在のUIに準拠）。

ComfyUI画面右上の歯車アイコンから設定を開く
「Enable Dev mode Options」にチェックを入れる
メニューに表示される「Save (API Format)」をクリック

通常のワークフローJSONにはノードの座標やグループ情報など、UI向けのデータが含まれています。一方、API形式のJSONはノードIDをキーとした実行専用の構造です。各ノードの class_type・inputs だけが含まれ、ノード間の接続は ["ノードID", 出力スロット番号] で表現されます。

編集部では、API形式のJSONをテンプレートとして保存し、Pythonスクリプトからプロンプトやシード値だけを差し替える運用を推奨しています。テンプレート化しておけば、同じワークフローを何百回でも再利用できます。

PythonからComfyUI APIを実行する手順

PythonでComfyUI APIを操作するには、requests と websocket-client の2つのライブラリが要ります。

requests + websocket-clientによる基本実装

まずインストールします。

pip install requests websocket-client

基本的な実行フローは以下の4段階です。

import json
import uuid
import requests
import websocket

SERVER = "127.0.0.1:8188"
CLIENT_ID = str(uuid.uuid4())

ws = websocket.WebSocket()
ws.connect(f"ws://{SERVER}/ws?clientId={CLIENT_ID}")

# 2. /promptにワークフローを送信
with open("workflow_api.json", "r") as f:
    prompt = json.load(f)

res = requests.post(
    f"http://{SERVER}/prompt",
    json={"prompt": prompt, "client_id": CLIENT_ID}
)
prompt_id = res.json()["prompt_id"]

# 3. WebSocketで完了を待機
while True:
    msg = ws.recv()
    if isinstance(msg, str):
        data = json.loads(msg)
        if data["type"] == "executing":
            d = data["data"]
            if d["prompt_id"] == prompt_id and d["node"] is None:
                break

# 4. /historyから出力情報を取得
history = requests.get(
    f"http://{SERVER}/history/{prompt_id}"
).json()

WebSocketメッセージには主に4種類の type があります。status はキュー状態、executing は実行中ノード、progress は長尺ノード（KSampler等）のステップ進捗、executed はノード完了時の出力情報です。ジョブ全体の完了判定は executing の node フィールドが None になった瞬間が最も確実になります。

client_id を付与しておくと、自クライアント宛のメッセージだけをサーバーが送ってくれるため、複数クライアントで同じComfyUIを共有する場面でも取り違えません。

バッチ画像生成の実装例

CSVファイルからプロンプトを読み込み、連続で画像を生成する実装例です。

import csv
import time
import copy

with open("prompts.csv", "r", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    for i, row in enumerate(reader):
        workflow = copy.deepcopy(prompt_template)
        # KSamplerノードのシードを変更
        workflow["3"]["inputs"]["seed"] = int(time.time()) + i
        # CLIPテキストノードのプロンプトを差し替え
        workflow["6"]["inputs"]["text"] = row["prompt"]

        res = requests.post(
            f"http://{SERVER}/prompt",
            json={"prompt": workflow, "client_id": CLIENT_ID}
        )

        if res.status_code != 200:
            print(f"エラー: 行{i+1} - {res.text}")
            continue

        # 完了を待機してから次のジョブへ
        wait_for_completion(ws, res.json()["prompt_id"])
        print(f"完了: {i+1}行目")

実務では、1,000枚以上のバッチ生成を行う場合にリトライ処理を追加しておくと安心です。ネットワーク切断やVRAM枯渇で失敗した行を記録し、再実行できる仕組みにしておくと運用が安定します。本番運用の規模になると、/queue をポーリングしてFIFOで投入制御するか、RedisやRQなどの外部キューを前段に挟む構成が定番です。

Node.jsからの実行とWebSocket監視

Node.jsからComfyUI APIを操作する場合も、基本的な流れはPythonと同じです。

const WebSocket = require("ws");

const SERVER = "127.0.0.1:8188";
const CLIENT_ID = crypto.randomUUID();

// WebSocket接続
const ws = new WebSocket(`ws://${SERVER}/ws?clientId=${CLIENT_ID}`);

// /promptにワークフローを送信
async function queuePrompt(workflow) {
  const res = await fetch(`http://${SERVER}/prompt`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: workflow,
      client_id: CLIENT_ID,
    }),
  });
  return await res.json();
}

// WebSocketで完了を監視
ws.on("message", (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.type === "executing" && msg.data.node === null) {
    console.log("ジョブ完了:", msg.data.prompt_id);
  }
});

Pythonとの違いは、Node.jsではイベントドリブンでWebSocketメッセージを処理する点です。複数ジョブを同時にキューイングする場合はPromiseベースの管理が適しています。WebアプリケーションのバックエンドとしてComfyUIを組み込む場合には、Node.jsのほうが親和性が高いでしょう。

認証・セキュリティ設定のポイント

ComfyUI APIをネットワーク経由で公開する場合、セキュリティ対策が欠かせません。

既定では 127.0.0.1（localhost）からのアクセスのみ許可されています。--listen 0.0.0.0 オプションで外部アクセスを開放できますが、認証なしの状態では誰でもワークフローを実行できてしまう状態です。

security_levelの4段階と推奨設定

config.ini の security_level は、2026年4月現在で4段階が定義されています。

レベル	概要	用途
`normal`	既定値。LANからのアクセスは拒否	ローカル単独利用
`normal-`	LANからのアクセスを許可（`--listen`使用時はこの値以下が必要）	LAN共有
`middle`	一部の権限チェックを緩和	検証環境
`high`	任意ファイル読み書きなどを許可（危険）	非推奨

--listen を指定してもLANから繋がらない場合、security_level が normal のままになっているケースが大半です。その際は normal- に下げるだけで解消します。weak への変更や high での公開は避けてください。

リバースプロキシ・ファイアウォールによる補強

ComfyUI単体の認証機能に頼らず、前段にWebサーバーを置く構成が実運用では安定します。

対策	方法
リバースプロキシ	nginxやCaddyでBasic認証・OAuth認証を前段に追加
ファイアウォール	特定IPアドレスのみポート8188を許可
VPN	Tailscale等でLAN相当の閉域網を作り、そこにのみ公開

編集部では、本番環境ではリバースプロキシとBasic認証の組み合わせを推奨しています。ComfyUI本体の更新に認証機能が左右されず、Webサーバー側で細かく制御できるためです。

API Nodeを使う場合のAPI Key渡し方

2025年以降、ComfyUI公式のAPI Node（BFLやOpenAI等の外部API連携ノード）を使う場面では、ComfyUI Account API Keyの指定が必須になりました。APIからAPI Nodeを呼び出す場合、POSTボディの extra_data.api_key_comfy_org フィールドにAPI Keyを埋め込む方式が公式仕様です（2026年4月現在）。

{
  "prompt": { ... },
  "client_id": "UUID",
  "extra_data": {
    "api_key_comfy_org": "YOUR_API_KEY"
  }
}

API Keyは platform.comfy.org でログイン後に発行できます（2026年4月現在）。ヘッドレス運用でAPI Nodeを使う場合、この方式が唯一の公式サポートです。旧来の「API Nodeはフロントエンド経由のみ」という制限は撤廃されました。

まとめ

ComfyUI APIは /prompt エンドポイントを軸に、プログラムからの画像生成を効率化できます。

要点を整理します。

/prompt にAPI形式のワークフローJSONをPOSTし、ジョブをキューに投入する
WebSocket接続で status・executing・progress・executed の4種メッセージを監視し、/history で結果を取得する
ワークフローJSONは「Save (API Format)」でエクスポートし、テンプレートとして再利用する
img2imgやControlNetは /upload/image で入力画像を先送りしてからPOSTする
公開時は security_level の段階選定と、リバースプロキシ・API Key認証の組み合わせで守る