> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 設計ノート

> Comfy API v2が存在する理由、既存のComfyUI APIとの関係、そして今後の予定について

\#intro

[Comfy SDKs](/ja/development/api-development/sdks)と、それらが呼び出す[Comfy API v2](/ja/api-reference/v2/overview)の背景です。SDKを使用するにあたり、この背景知識は必要ありません。新しいAPIと既存APIのどちらを基盤に構築するかを検討している場合は、お読みください。

## なぜ新しい API なのか

既に HTTP 経由で `/prompt` と `/history` を呼び出して ComfyUI を操作できます。これらのエンドポイントは ComfyUI の Web UI を支えるために存在しており、それらを基に構築することは、あなたに約束されていない内部実装に依存することを意味します。v2 API は、それらが提供できない 3 つのものを追加します。

**確約。** v2 はバージョン管理され、ドキュメント化され、サポートされています。v2 内での変更は追加的なものです。破壊的な変更は v3 としてリリースされます。ComfyUI の新しいリリースによってあなたの統合が壊れることはありません。

**移植性。** ローカルの ComfyUI に対しても、Comfy Cloud に対しても、後で提供する他の何に対しても、同じ動作を実現します。同じコードで、異なるベース URL です。

**本番環境に耐える形状。** 永続的なジョブ ID、冪等な送信、型付きエラー、正規化された出力、そして真のバックプレッシャーを備え、すべての統合が `prompt_id` と `/history` の上にこれら 5 つを再発明する必要はありません。

## 既存のエンドポイントをラップしない理由

それらは、一度に1つのワークフローを実行する単一のComfyUIインスタンスを前提としており、その前提が`prompt_id`、`/history`、およびWebSocketプロトコルに組み込まれているためです。

v2 APIはその前提を持ちません。同時に多数のワークフローが実行され、それぞれが永続的なジョブIDで識別されることが、例外ではなくデフォルトのケースです。

## まずポーリング、進捗はストリームで

v2 のすべての機能は、通常の GET リクエストで利用できます。`GET /api/v2/jobs/{id}` は、現在のステータス、最新の進捗スナップショット、およびこれまでにコミットされたすべての出力を返します。これはジョブの正規のビューであり、ジョブの `expires_at` まで利用可能です。

`GET /api/v2/jobs/{id}/events` の SSE ストリームは、両 SDK で `job.events()` として公開されており、その上に構築されたライブ拡張機能です。プログレスバーを駆動するために使用してください。真実のソースとして使用しないでください。イベント ID はなく、再開カーソルもなく、切断されていた間に送信されたフレームは失われます。

正規の方法がストリームやウェブフックではなくポーリングである理由は 2 つあります。

* ワークフローは長時間実行される可能性があります。3 秒間接続が途切れても、結果を失うことは決してないはずです。
* ウェブフックは、公開アドレスを持つサービスには適しています。ポートで待ち受けていない個人のデスクトップ上の Blender プラグインには機能せず、また機能すべきでもありません。

実際の効果として、すべてのステップが再開可能です。プロセスがジョブの途中でクラッシュした場合、1 時間後に戻ってきても、`GET /api/v2/jobs/{id}` にはステータスと出力がまだあります。他のトランスポートは、それに適したケースのために後で追加される可能性があります。この方法はどこでも機能します。

## 既存APIとの関係

非推奨となるものはありません。`/prompt`、`/history`、`/ws`、およびその他のAPIは引き続き動作し、[Cloud API](/ja/development/cloud/overview)も動作し続けます。現在動作している統合は、これによって壊れることはありません。この2つは共存します。

|              | Comfy API v2                         | 既存API                        |
| ------------ | ------------------------------------ | ---------------------------- |
| **互換性**      | バージョン管理されている。v2内では追加変更のみ             | リリース間の互換性は保証されない             |
| **並行処理モデル**  | 複数のジョブを同時実行でき、それぞれに永続的なIDがある         | 1つのインスタンスにつき、同時に1つのワークフロー    |
| **実行対象**     | Comfy Cloudとセルフホスト型ComfyUI、同一のコントラクト | Cloud APIとComfyUIサーバーAPIは異なる |
| **公式クライアント** | PythonおよびTypeScript SDK              | なし                           |
| **最適な用途**    | 新規の統合                                | すでに動作している統合                  |

## 最初のバージョンの範囲

ひとつのことをきちんと実現する: ワークフローを実行し、結果を取得する。入力をアップロードし、API形式のグラフを送信し、実行を監視し、出力を取得する。

これが意図的に設定された全体の範囲です。保存されたワークフロー、モデルライブラリ管理、ノードのイントロスペクション、名前付きワークフローパラメータはまだここにはありません。ComfyUIが展開されるあらゆる方法で確実にサポートできる小さな範囲を提供するほうが、一部の方法でしか機能しない大きな範囲を提供するよりも望ましいと考えています。ここから成長していきます。

## ローカルプロキシ

ベータ期間中、セルフホスト型ComfyUIは[comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy)を介してv2で通信します。このプロキシはインスタンスと並行して実行され、その前面でv2コントラクトを提供します。これはオープンソースであり、あくまで一時しのぎの措置です。APIが安定化すると、これはComfyUIコアに組み込まれ、プロキシは不要になります。

## なぜPythonとTypeScriptが最初なのか

それは、すでにComfyUIをスケール環境で運用している人々に尋ねたところ、需要があったのがこの2言語だったからです。両SDKは同じ文書化されたHTTPコントラクトに基づいているため、どの言語でも今すぐAPIを利用できます。他の言語のファーストパーティSDKをご希望の場合は、[当Discord](https://discord.com/invite/comfyorg) の `#developer-platform` チャンネルでお知らせください。

## 私たちがあなたに求めていること

APIが`0.1.x`であるのには理由があります。今後数週間でAPIのインターフェースを固定する予定です。メソッド名、クライアントの形状、イベントカタログ、エラーの分類体系、そして実際のアセット処理の使用感は、今のうちならまだ簡単に変更できます。[フィードバック](/ja/development/api-development/sdks#feedback)を参照してください。