ComfyUIをヘッドレスAPIサーバーとして実装する：Pythonによる画像生成パイプライン構築の技術仕様書

はじめに：GUIは「開発環境」、APIこそが「本番環境」

「ComfyUIで生成される画像の品質は素晴らしい。でも、これをどうやって自社のWebアプリや社内システムに組み込めばいいんだ？」

もしバックエンドエンジニアなら、ComfyUIのリポジトリをCloneし、起動した直後にこう思ったはずです。「APIドキュメントはどこだ？」と。

検索して出てくるのは、魅力的なイラストの作り方や、複雑なカスタムノードの紹介記事ばかり。システム開発において求められているのはHTTPリクエストの仕様書であり、ペイロードとなるJSONのスキーマ定義であり、非同期処理をハンドリングするためのステートマシン図です。

正直に言えば、ComfyUIにおけるGUI画面は、APIに投げるためのJSONを生成するための「ビジュアルエディタ（IDE）」に過ぎません。

ComfyUIのバックエンドは、極めて堅牢で拡張性の高いイベント駆動型のPythonサーバーです。これを正しく理解し、Headless（GUIなし）なAPIサーバーとして制御できれば、高価なSaaS型画像生成APIに頼ることなく、自社専用の画像生成パイプラインを構築できます。レート制限に怯えることも、ブラックボックスな課金体系に悩むこともありません。

この記事では、クリエイティブテックの現場で実践されている、ComfyUIを「システム基盤」として扱うための技術仕様を共有します。これは、画像を作るための記事ではありません。画像を作るシステムを作るための技術仕様書です。技術的な実現可能性と、実際の制作フローにおける利便性を両立させる視点で解説します。

1. アーキテクチャ概要：Headless ComfyUI

コードを書く前に、まずはComfyUIがどのように動作しているかをエンジニアリングの視点で解剖します。ここを正確に理解していないと、後のインテグレーションで必ず躓きます。

GUI版とAPIモードの関係性

普段ブラウザで操作するComfyUIの画面は、Pythonバックエンド（aiohttpベースのサーバー）に対してAPIリクエストを送っている単なるJavaScriptクライアントにすぎません。つまり、ブラウザが行っている通信を外部プログラム（PythonスクリプトやNode.jsサーバーなど）で模倣すれば、ComfyUIはそのままAPIサーバーとして機能します。

特別な「APIモード」というスイッチがあるわけではありません。しかし、サーバー起動時にGUIを立ち上げず、リソースをバックエンド処理に集中させる運用が基本となります。起動引数に --listen を付与し、外部からの接続を受け付ける状態にするだけで、それは立派なAPIサーバーへと変貌します。

WebSocketとHTTPの役割分担

ComfyUIの通信アーキテクチャは、HTTPとWebSocketのハイブリッド構成です。ここがRESTful APIに慣れたエンジニアが最初に戸惑うポイントです。

• HTTP (RESTful): 生成リクエストの送信（キューイング）、生成履歴の取得、画像のアップロード、システム情報の取得など、「静的」なアクションを担当します。
• WebSocket: キューの状況、ノードごとの実行進捗、エラー通知、生成完了のリアルタイム通知など、「動的」なステータス管理を担当します。

一般的な画像生成APIのように、POST /generate でリクエストを投げればレスポンスで画像バイナリが返ってくるわけではありません。返ってくるのは prompt_id というUUIDだけです。クライアントはWebSocketを通じて処理の完了を監視し、完了イベント（executed）を受け取った後に、改めてファイル名指定で画像を取得しに行く必要があります。

この非同期イベント駆動アーキテクチャを前提にシステムを設計することが不可欠です。

システム統合における推奨構成

本番環境でComfyUIをホスティングする場合、セキュリティと運用安定性を考慮した以下の構成が業界標準となっています。

• コンテナ化による環境固定:
  ComfyUIやPyTorch、CUDAドライバのバージョン不整合は致命的なエラーを引き起こします。Dockerを使用して実行環境を完全に固定することが必須です。最新のDocker環境では一部の旧機能が削除されているケースもあるため、必ず互換性を確認した上でワークフローを更新してください。また、CUDAの最新バージョンでは重大な脆弱性が修正されていることが多いため、NVIDIAが提供するNGCコンテナなどを活用し、セキュアで安定した実行環境を構築することを強く推奨します。古いGPUアーキテクチャは最新のCUDA環境でサポート外となる場合がある点にも注意が必要です。
• ストレージの分離と永続化:
  モデルファイル（CheckpointやLoRA）は数GB〜数百GBに及びます。これらはコンテナ内には含めず、外部ボリュームやNASに配置してマウントする構成が一般的です。これにより、コンテナの再構築時にもデータを保持でき、ストレージコストの最適化も図れます。運用上の注意点として、悪意のあるコードが実行されるリスクがある旧形式（.ckpt）は避け、安全な形式（.safetensors）を優先して使用してください。また、ベースモデルとLoRAの互換性を考慮したディレクトリ設計やバージョン管理が求められます。
• セキュリティレイヤーの追加:
  ComfyUI自体には高度な認証機能やアクセス制御機能が実装されていません。そのままインターネットに公開することは極めて危険です。必ずNginxなどのリバースプロキシを前段に配置し、Basic認証、IP制限、あるいはOAuthプロキシによる認証機構を実装してください。また、APIエンドポイントへのレートリミット設定も、リソース枯渇攻撃への対策として有効です。

2. ワークフロー形式仕様（Prompt Format）

API連携で最も開発者を悩ませるのが、リクエストボディとして送信するJSONデータの構造です。GUIで「Save」ボタンを押して保存される .json ファイル（Workflow形式）と、APIが受け付けるJSON（API形式）は別物です。

API向けJSON構造の解析

GUIで保存したJSONには、ノードの座標データやUI上のグループ情報など、レンダリング用のメタデータが大量に含まれています。しかし、APIが必要とするのは「実行に必要な情報」だけです。

API形式のJSON（Prompt format）を取得するには、ComfyUIの設定（歯車アイコン）から "Enable Dev mode Options" をオンにします。するとメニューに "Save (API Format)" というボタンが出現します。これこそが、システム連携に必要となる真のJSONです。

構造は以下のようになっています。

{
  "3": {
    "class_type": "KSampler",
    "inputs": {
      "seed": 156680208700286,
      "steps": 20,
      "cfg": 8,
      "sampler_name": "euler",
      "scheduler": "normal",
      "denoise": 1,
      "model": ["4", 0],
      "positive": ["6", 0],
      "negative": ["7", 0],
      "latent_image": ["5", 0]
    }
  },
  "4": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": {
      "ckpt_name": "v1-5-pruned-emaonly.ckpt"
    }
  }
  // ... 他のノードが続く
}

キーとなる数字（"3", "4"...）はノードIDです。inputs の中にある ["4", 0] といった配列が、ノード間の接続（リンク）を表しています。「ノードID 4の、0番目の出力を使う」という意味です。

動的パラメータの注入ポイント

システム化する際は、このJSONをテンプレートとして扱い、必要な箇所をプログラムで書き換えて送信します。

例えば、ユーザーの入力に応じてプロンプトを変えたい場合は、CLIPTextEncode ノード（通常はID 6や7あたり）の text フィールドを置換します。シード値をランダムにしたい場合は、KSampler ノードの seed フィールドを乱数で上書きします。

注意点: ノードIDはワークフローを編集するたびに変わる可能性があります。ハードコーディングせず、class_type や _meta 情報を元に動的に対象ノードを特定するロジックを組むか、ワークフローの変更を厳格に管理する必要があります。

3. コアエンドポイント仕様

外部システムからComfyUIを制御するために必須となる、主要なAPIエンドポイントをリファレンスとしてまとめます。これさえ押さえておけば、基本的なパイプラインの制御は十分に可能です。

POST /prompt（キューイング）

画像生成ジョブをサーバーのキューに登録します。

• Payload:

  {
    "prompt": { ...API形式のJSONオブジェクト... },
    "client_id": "unique_client_id_string"
  }
  

• Response:

  {
    "prompt_id": "<UUID>",
    "number": <Queue Position>,
    "node_errors": {}
  }
  

client_id は非常に重要です。これを指定することで、WebSocket接続とHTTPリクエストを正確に紐付け、特定のクライアントに対するイベント通知をリアルタイムで受け取れるようになります。

GET /history/{prompt_id}（結果取得）

生成が完了したジョブの結果情報を取得します。ここには生成された画像のファイル名やサブディレクトリ情報が詳細に含まれます。クリエイティブ制作の自動化においては、この履歴データをもとに次の処理プロセスへ繋ぐ設計が基本となります。

POST /view（画像プレビュー）

生成された画像ファイルを取得します。GETリクエストでも取得可能ですが、パラメータ指定が直感的で扱いやすい設計になっています。

• Query Parameters:
  • filename: 生成されたファイル名
  • subfolder: サブフォルダ（ある場合）
  • type: output（成果物）または temp（プレビュー用一時ファイル）

POST /upload/image（素材アップロード）

img2imgやControlNet用に、ベースとなる参照画像をサーバーへアップロードします。multipart/form-data 形式で送信し、レスポンスとしてワークフロー内で指定すべきファイル名が返ってきます。

ここで重要なのは、アップロードした画像を処理するControlNetノードの最新仕様です。現在のComfyUI環境では、旧来のノードが廃止され、新たに「Apply ControlNet (Advanced)」（ControlNetApplyAdvancedクラス）への移行が必須となっています。これにより、ポジティブ・ネガティブ条件データに対して start_percent や end_percent を用いた段階的な適用タイミングの制御や、strength による細かな影響度の調整が可能になりました。

例えば、公式ドキュメントによると、Stability AIから提供されているStable Diffusion 3.5 Large専用のControlNet（Blur、Canny、Depthなど）を活用した高解像度化やエッジ制御、あるいはFLUX対応のControlNet Unionを組み込む際にも、このエンドポイントでアップロードした素材を最新のAdvancedノードに渡すことで、より精緻で意図通りのクリエイティブ制御が実現できます。旧仕様に依存したワークフローやAPIリクエストを構築している場合は、早急にAdvancedノードのパラメータ構成へと置き換えることを推奨します。

4. WebSocketイベントストリーム仕様

HTTPポーリングでステータスを確認するのは非効率であり、サーバー負荷も高まります。ComfyUIはWebSocketを通じて詳細なイベントをプッシュ通知してくれます。

接続確立とハンドシェイク

接続先は /ws?clientId={client_id} です。ここで指定する client_id は、POST /prompt で送信するものと同一である必要があります。

実行状況通知（executing/progress）

生成プロセス中、以下のタイプのメッセージが流れてきます。

• status: 現在のキューの残り数など、全体の状態。
• execution_start: 特定のプロンプトIDの処理が開始された。
• executing: 特定のノードが実行中になった。node フィールドにノードIDが入ります。これを監視することで、「現在KSamplerが動作中」といった進捗表示が可能になります。
• progress: KSamplerなどの重い処理の進捗（ステップ数）。value と max が送られてくるので、プログレスバーの実装に使えます。

生成完了通知（executed）

全ての処理が完了すると executed イベントが飛びます。

{
  "type": "executed",
  "data": {
    "node": "9", // SaveImageノードのID
    "output": {
      "images": [
        {
          "filename": "ComfyUI_0001.png",
          "subfolder": "",
          "type": "output"
        }
      ]
    },
    "prompt_id": "<UUID>"
  }
}

このイベントを受け取ったら、output.images に含まれるファイル情報を元に、POST /view で画像をダウンロードしに行きます。これが一連のフローのゴールです。

5. 実装パターンとコード例

論より証拠。Pythonを使って「ワークフローを送信し、完了を待機し、画像を保存する」一連の処理を行う最小限のクライアントコードを示します。

PythonによるAPIクライアント実装

import websocket
import uuid
import json
import urllib.request
import urllib.parse

server_address = "127.0.0.1:8188"
client_id = str(uuid.uuid4())

def queue_prompt(prompt):
    p = {"prompt": prompt, "client_id": client_id}
    data = json.dumps(p).encode('utf-8')
    req = urllib.request.Request(f"http://{server_address}/prompt", data=data)
    return json.loads(urllib.request.urlopen(req).read())

def get_image(filename, subfolder, folder_type):
    data = {"filename": filename, "subfolder": subfolder, "type": folder_type}
    url_values = urllib.parse.urlencode(data)
    with urllib.request.urlopen(f"http://{server_address}/view?{url_values}") as response:
        return response.read()

def get_history(prompt_id):
    with urllib.request.urlopen(f"http://{server_address}/history/{prompt_id}") as response:
        return json.loads(response.read())

# WebSocket接続
ws = websocket.WebSocket()
ws.connect(f"ws://{server_address}/ws?clientId={client_id}")

# ワークフローJSONの読み込み（API Formatで保存したもの）
with open("workflow_api.json", "r", encoding="utf-8") as f:
    prompt_text = json.load(f)

# ここでprompt_textの中身を動的に書き換える
prompt_text["3"]["inputs"]["seed"] = 123456789 # 例: シード固定

# キューに登録
prompt_id = queue_prompt(prompt_text)['prompt_id']

# WebSocketで完了待機
while True:
    out = ws.recv()
    if isinstance(out, str):
        message = json.loads(out)
        if message['type'] == 'executing':
            data = message['data']
            if data['node'] is None and data['prompt_id'] == prompt_id:
                break # 完了！

# 履歴から画像情報を取得してダウンロード
history = get_history(prompt_id)[prompt_id]
for node_id in history['outputs']:
    node_output = history['outputs'][node_id]
    if 'images' in node_output:
        for image in node_output['images']:
            image_data = get_image(image['filename'], image['subfolder'], image['type'])
            with open(image['filename'], "wb") as f:
                f.write(image_data)
            print(f"Saved: {image['filename']}")

このコードはあくまで基本形です。実際の本番環境では、websocket-client ライブラリなどを使ってより堅牢なイベントループを実装し、タイムアウト処理や再接続ロジックを組み込む必要があります。

6. 制約事項と最適化

最後に、商用利用やシステム組み込み時に直面する「落とし穴」と、その回避策について触れておきます。

モデルロード時間の短縮テクニック

ComfyUIは賢く、ワークフローが変わってもモデルに変更がなければメモリ上のモデルを再利用します。しかし、異なるCheckpointを使用するリクエストが交互に来ると、その都度数GBのモデルロードが発生し、レスポンスタイムが数十秒〜数分遅延します。

対策としては、モデルごとに専用のComfyUIインスタンス（コンテナ）を用意し、前段のロードバランサでリクエストを振り分けるのが定石です。「アニメ系モデル専用サーバー」「実写系専用サーバー」のように役割を分けることで、キャッシュヒット率を最大化できます。

カスタムノード依存の管理

ComfyUIの魅力は豊富なカスタムノードですが、システム運用においてこれらは「依存関係のリスク」となります。ある日突然、作者がリポジトリを消したり、アップデートで仕様が変わったりすることが日常茶飯事です。

開発環境で動作確認が取れたら、custom_nodes フォルダごとGitで管理するか、Dockerイメージに焼き込んで塩漬けにすることを強く推奨します。「最新版ならもっと速くなるかも」という誘惑には負けないでください。安定稼働が最優先です。

セキュリティ上の注意点

繰り返しになりますが、ComfyUIはローカル利用を前提に設計されており、セキュリティ機能は皆無です。特に Manager ノードなどを入れている場合、API経由で任意のPythonコードを実行されたり、システムファイルを読み書きされるリスクがあります。

本番環境用のコンテナでは、ComfyUI-Manager などの管理系ノードは削除し、OSレベルでの権限を最小限に絞る必要があります。また、APIのエンドポイントも必要なもの以外はリバースプロキシでブロックする運用が望ましいでしょう。

まとめ：自社構築の壁と、その先にある自由

ComfyUIをAPIサーバーとして活用することで、画像生成AIのポテンシャルは飛躍的に広がります。Webサービスへの組み込み、社内ツールの自動化、大量画像のバッチ処理など、アイデア次第でどんなシステムも構築可能です。

しかし、ここまで読み進めたエンジニアの方ならお気づきでしょう。「動かすのは簡単だが、安定して運用し続けるのは骨が折れる」という事実に。

• GPUリソースの効率的なスケジューリング
• VRAM不足エラー（OOM）からの自動復旧
• 頻繁なアップデートへの追従とバージョン管理
• 数百GBに及ぶモデルファイルの管理

これらを全て自社でメンテナンスするには、専任のエンジニアチームが必要になるレベルです。「とりあえず動いた」から「サービスとして使える」までの距離は意外と遠いものです。

もし、ComfyUIの柔軟性は欲しいが、インフラ管理の泥沼にはまりたくない、あるいは最短距離で商用レベルの実装を完了させたいと考える場合は、専門家に相談することをおすすめします。画像生成パイプライン構築の知見を持つ専門家であれば、要件に最適なアーキテクチャ設計と実装の支援が可能です。無駄な開発コストをかける前に、最適なルートを検討することが重要です。