comfyui-api

ComfyUI API スキル

ComfyUI の REST API に接続して、ワークフローを実行し、進行状況を監視し、出力を取得します。

設定

• デフォルト URL：http://127.0.0.1:8188
• カスタム URL：プロジェクトマニフェストで設定するか、パラメーターとして渡します
• タイムアウト：API 呼び出しは 30 秒、生成のポーリングにはタイムアウトなし

2 つのモード

オンラインモード（ComfyUI 実行中）

API に完全にアクセスできます。対話型の作業に推奨されるモードです。

1. 接続をテスト：GET /system_stats
2. 機能を確認：comfyui-inventory スキルを使用
3. ワークフローをキューに追加：POST /prompt
4. 結果をポーリング：5 秒ごとに GET /history/{prompt_id}
5. 出力を取得：GET /view?filename=...

オフラインモード（サーバーなし）

ComfyUI で手動読み込みするため、ワークフロー JSON をエクスポートします。

1. ComfyUI の形式に従ってワークフロー JSON を生成
2. projects/{project}/workflows/{name}.json に保存
3. ComfyUI にドラッグ＆ドロップするようユーザーに案内

API 操作

サーバーのステータスを確認

curl http://127.0.0.1:8188/system_stats

レスポンスフィールド：

• system.os：オペレーティングシステム
• system.comfyui_version：バージョン文字列
• devices[0].name：GPU 名
• devices[0].vram_total：VRAM の合計バイト数
• devices[0].vram_free：空き VRAM のバイト数

ワークフローをキューに追加

curl -X POST http://127.0.0.1:8188/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": WORKFLOW_JSON, "client_id": "video-agent"}'

WORKFLOW_JSON 形式：

{
  "1": {
    "class_type": "LoadCheckpoint",
    "inputs": {
      "ckpt_name": "flux1-dev.safetensors"
    }
  },
  "2": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "photorealistic portrait...",
      "clip": ["1", 1]
    }
  }
}

各ノードには文字列 ID がキーとして割り当てられます。入力では、["{node_id}", {output_index}] の形式で他のノードを参照します。

レスポンス：

{"prompt_id": "abc-123-def", "number": 1}

完了をポーリング

curl http://127.0.0.1:8188/history/abc-123-def

未完了：{}（空のオブジェクト）を返します 完了：出力を含む実行データを返します：

{
  "abc-123-def": {
    "outputs": {
      "9": {
        "images": [{"filename": "ComfyUI_00001.png", "subfolder": "", "type": "output"}]
      }
    },
    "status": {"completed": true}
  }
}

出力画像を取得

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

参照画像をアップロード

curl -X POST http://127.0.0.1:8188/upload/image \
  -F "[email protected]" \
  -F "subfolder=input" \
  -F "type=input"

現在の生成をキャンセル

curl -X POST http://127.0.0.1:8188/interrupt

VRAM を解放

curl -X POST http://127.0.0.1:8188/free \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true}'

ポーリング戦略

ComfyUI は CLI コンテキストで WebSocket をサポートしていません。REST ポーリングを使用します：

1. POST /prompt でワークフローをキューに追加し、prompt_id を取得
2. 5 秒ごとに GET /history/{prompt_id} をポーリング
3. 空のレスポンスの場合：生成中のため、ポーリングを続行
4. データを含むレスポンスの場合：status.completed を確認
5. completed: true の場合、出力を抽出
6. ステータスにエラーがある場合は、comfyui-troubleshooter に引き継ぐ

タイムアウト：ポーリングを 10 分続けたらユーザーに警告します。動画生成（Wan 14B）には 15～30 分かかる場合があります。

ワークフローの検証

ワークフローをキューに追加する前に、次の手順を実行します：

1. state/inventory.json を読み込む（comfyui-inventory 経由）
2. ワークフロー内の各ノードについて、class_type がインストール済みノードに存在することを確認
3. 各モデル参照について、インストール済みモデルにファイルが存在することを確認
4. 不足している項目を次のように示す：
   • ノード：ComfyUI-Manager のインストールコマンドを提案
   • モデル：references/models.md からダウンロードリンクを提示
   • バージョンの不一致：更新を提案

エラー処理

エラー	原因	対処
接続拒否	ComfyUI が実行されていない	オフラインモードに切り替えて JSON を保存
400 Bad Request	無効なワークフロー JSON	ノードの接続を検証
500 Internal Error	ComfyUI のクラッシュ	再起動を提案し、ログを確認
タイムアウト（レスポンスなし）	サーバーの過負荷	待機してから一度再試行

参照資料

API ドキュメント全文：foundation/api-quick-ref.md