krea/krea-3 のAPIリファレンスです。Comfy Router が Krea から提供しています。
入力: テキスト、画像 · 出力: 画像
クイックスタート
Comfy ワークスペースでキーを作成し、COMFY_API_KEY としてエクスポートします。Python と TypeScript のスニペットは Comfy SDK(pip install comfy-sdk と npm install @comfyorg/sdk)を使用します。cURL のスニペットは、同じ呼び出しを生の HTTP で行うものです。
モデルID: krea/krea-3
エンドポイント: POST https://api.comfy.org/v2/models/krea/krea-3
- 結果を待つ
- キューに送信して後で取得
同じボディを
POST https://api.comfy.org/v2/models/krea/krea-3/requests に送信します。Router は実行が受け付けられ次第、201 と request_id を返し、結果は準備ができ次第、このプロセスまたは別のプロセスから取得されます。キューの配信では、ステータス、キャンセル、取得について説明します。スキーマ
入力
入力画像URL。最大8件です。8件を超えるエントリは取得を行う前に拒否されます(/proxy/krea では 400、Comfy Router のスキーマチェックは先に 422 を返します)。画像を POST /proxy/krea/assets にアップロードしたときに返される image_url(multipart フォームのフィールド
file)は常に受け付けられます。その他の公開 https URL が受け付けられるかどうかは環境によって異なります。受け付けられない環境では、ホスト app-uploads.krea.ai 上の https URL 以外のリンクはすべて 400 で拒否され、‘image_urls must be image_url values returned by POST /proxy/krea/assets’ と表示されるため、代わりに画像をアップロードしてください。受け付けられる環境では、公開されている https の画像URLはすべて受け付けられ、形式が不正な URL や https でない URL は 400 で拒否されます(ポートが数値でも範囲外である URL はこのチェックでは捕捉されず、代わりに 502 で失敗することがあります)。その場合、app-uploads.krea.ai へのリンクではない image_urls のエントリ(公開 https URL、またはそれらが受け付けられる環境では base64 の data: URI)を含むリクエストも、取得を行う前に 400 で拒否されます。ただし、リクエストボディ全体が multipart ではなく application/json として送信され、有効な UTF-8 であり、25100288 バイト以下で、このスキーマが宣言するフィールドのみを含む場合は除きます。その場合、形式が正しい https URL については、呼び出し側が修正できる参照はそのホスト名を示して 400 で拒否されます。具体的には、取得前のチェックでホストが解決できない、または公開的に到達できない、許可された回数を超えてリダイレクトする、https でない URL や公開的に到達できないホストへリダイレクトする、408 と 429 以外の 4xx を返す、画像ではない、読み取れない形式の画像である、画像サイズヘッダーが最初の 2 MiB 以内にない、あるいは宣言された長さもチャンクエンコーディングもないレスポンスが画像サイズヘッダーより前に終了する、といった場合です。それ以外の取得時の失敗は、POST /proxy/krea で 502 エラーになります(Comfy Router は 500 internal_error で応答します)。一時的な DNS、TLS、接続の失敗、タイムアウト、配信元の 408、429、5xx その他の 200 以外のステータス、あるいはチェックは通過したものの取得時の接続で解決できない、または公開的に到達できないホストなどです。これらの一部は再試行で解消します(リゾルバーのエラー、タイムアウト、切断された接続、5xx、408、429 を返す配信元、ホストチェックと接続の間に DNS の応答が非公開アドレスに切り替わるホストなどで、再試行すると成功するか、非公開ホストに対する 400 になることがあります)。一方、毎回同じように失敗するものもあります。たとえば、取得が信頼しない TLS 証明書(自己署名、期限切れ、ホスト名の不一致)、200 以外の 2xx や取得が追従しない 3xx(204、206、300、304、305、Location のない 301、302、303、307、308 など)を返す配信元です。再試行しても同じように失敗する場合は、代わりに画像をアップロードしてください。Comfy Router 経由でキューに入れたリクエストは、image_urls のいずれかが app-uploads.krea.ai へのリンクでない場合、そのような失敗を再試行しないため、原因が解消しうる場合はご自身で再送信してください。その他の URL が受け付けられない環境では、実際のアップロードではない app-uploads.krea.ai へのリンクは 5xx エラーで失敗します。受け付けられる環境では、他の到達不能な参照と同様に 400 で拒否されます。サーバーがどちらに該当するかをまだ学習していない間は、ホストが app-uploads.krea.ai へのリンクでない https URL は、公開・非公開を問わず、再試行しても安全な 503 エラーで失敗します(キュー中のリクエストは自動的に再試行されます)。キュー中のリクエストの 400 には汎用的な invalid_input の詳細しか含まれないため、ホスト名も上記の文言も示されず、キューはそれを再試行しません。キュー中の 400 は image_urls だけでなく任意のフィールド(たとえば未対応の解像度や thinking_mode)に起因する可能性があるため、まず他のフィールドを確認してください。それらが有効であれば、各画像を POST /proxy/krea/assets にアップロードし、その image_url の値と新しい Idempotency-Key(またはなし)で再送信してください。ボディを変更して同じキーを再利用すると 409 invalid_input で拒否され、画像に関する情報は何も示されません。同じボディで再利用すると 201 と元の request_id、Idempotent-Replayed: true が返るため新しい実行は開始されず、その結果 URL は同じ 400 を返します(ステータス URL は error_type invalid_input とともに 200 を返します)。他の公開 https URL が受け付けられる環境で、その再送信も 400 で失敗する場合、問題は画像自体にあります(たとえば未対応の画像である、画像サイズヘッダーが最初の 2 MiB 以内にない、など)。受け付けられない環境では、同じアップロード済み画像はその 400 の代わりに 5xx(Comfy Router では 500 internal_error)で失敗し、やはり問題は画像にあるため、再度アップロードしても解決しません。各画像のサイズを見つけるために読み取られるのは最初の 2 MiB だけです。そのため、そのウィンドウ内でサイズ情報を読み取れない画像(たとえば 2 MiB を超える埋め込みメタデータを持つ JPEG、またはパレット PNG で透明度データが、透明度がなければ最初の画像データチャンクの開始位置が 2 MiB を超えたところにあるもの、たとえば 2 MiB を超えるテキストチャンクやカラープロファイルチャンクの後にあるもの)は、アップロード済みかどうかに関係なく、画像サイズヘッダーが最初の 2 MiB 以内にないという 400 で拒否されます。大きなメタデータを除いて保存し直すか、パレット PNG を非パレット PNG として保存してください。国際化されたホストは ASCII(punycode)形式で送信してください。非 ASCII のホスト名は存在しないものとして拒否されます。テキストから画像への生成では省略します。GET /v2/models/krea/krea-3/openapi.json で Router が提供するスキーマから生成されています。これは、リクエストがプロバイダーに到達する前に呼び出しを検証する際に使用される同じドキュメントです。
出力
ジョブが失敗した理由: content_policy、invalid_request、validation_failed、model_unavailable、insufficient_balance、timeout、auto_cancelled、provider_error、internal、node_app_node_failed のいずれかです。不明なコードは internal として扱ってください。
完了した生成結果です。
KreaJob と異なり、ここでは null 許容ではありません。result に urls が含まれないターミナル状態のジョブは Comfy Router のエラーとして応答されるため、200 には必ずこれが含まれます。生成済みの画像をダウンロード可能なリンクとして示します。
urls が空の completed ジョブは success_without_output となり、このドキュメントに到達しないため、少なくとも1つ含まれます。このドキュメントでは常に
completed です。Router が成功として報告するのはこのステータスのみであり、Krea の語彙は大文字小文字を区別せずに照合されます。取りうる値: completed例
入力
出力
出荷前の確認
SDK はIdempotency-Key を生成し、自動リトライで再利用します。手動リトライでは元のキーを再利用してください。Router は最大 10 分間接続を保持できます。
リクエストが失敗すると、Router は理由を説明する X-Comfy-Error-Type レスポンスヘッダーを送信します。422 は、プロバイダーを呼び出す前に Router が入力を拒否したことを意味し、413 はリクエスト本文が Router の受け入れ可能なサイズを超えていたことを意味します。生成されたアセットは 結果 URL の有効期限 があるため、早めにダウンロードしてください。
上記のフィールド説明に記載されているサイズ制限は、プロバイダーの仕様から引用した、そのフィールドに対するプロバイダー自身の上限です。Router はリクエスト本文全体に対して別の上限を適用し、base64 エンコードされたメディアもこれにカウントされます。リクエスト本文のサイズ を参照してください。
このページは、Comfy Router 経由で呼び出す 1 つのパートナーモデルについて説明しています。同じ comfy-sdk / @comfyorg/sdk パッケージには、Comfy Cloud 上で ComfyUI のワークフローグラフ全体を実行するための 2 つ目のクライアントも含まれています: Comfy(api_key=...) / new Comfy({ apiKey })、および client.workflows、client.assets、client.jobs。Comfy SDKs を参照してください。
ヘッダー
認証、冪等性、リクエスト ID、エラー分類、リトライ間隔、支出上限。
Router API の利用
モデルの検出、バリデーションエラー、リトライ、課金。
制限事項
Router が現在対応していないことと、代替手段。