ideogram/ideogram-4-6 の API リファレンスです。Comfy Router が Ideogram から提供します。
入力: テキスト、画像 · 出力: 画像
クイックスタート
Comfy ワークスペースでキーを作成し、COMFY_API_KEY としてエクスポートします。Python と TypeScript のスニペットは Comfy SDK(pip install comfy-sdk と npm install @comfyorg/sdk)を使用しています。cURL のスニペットは、同じ呼び出しを生の HTTP で行うものです。
モデル ID: ideogram/ideogram-4-6
エンドポイント: POST https://api.comfy.org/v2/models/ideogram/ideogram-4-6
- 結果を待つ
- キューに入れて後で収集する
同じボディを
POST https://api.comfy.org/v2/models/ideogram/ideogram-4-6/requests に送信します。Router は実行が受け付けられるとすぐに 201 と request_id を返し、結果は準備ができ次第、このプロセスからでも別のプロセスからでも収集できます。キュー配信では、ステータス、キャンセル、収集の流れを説明します。スキーマ
入力
Precise Edit 専用。
image が必要です。auto(デフォルト)、4K または 8K 画像の一部をフル解像度で編集するための y,x,y,x 形式の領域、または画像全体を送信する none のいずれかです。画像 1 枚。呼び出し元に代わって Router が取得する https URL、またはバイト列をインラインで含む
data:image/<format>;base64,<payload> URI のいずれかの形式で指定します。受け付ける画像形式は png、webp、jpeg で、このセットはプロバイダーに委ねるのではなく解決時に強制されます。svg、gif、avif、tiff はここで拒否され、送信した画像を名指しして示します。原因から 2 ホップ離れたパートナーエラーにはなりません。
URL 形式を推奨します。base64 ペイロードは約 4/3 に膨らみ、リクエストボディ全体は 100 MiB に制限されるため、インライン形式ではソース画像が約 75 MB で上限に達します。URL ならこれを完全に回避できます。この説明の末尾に記載する画像ごとおよびリクエストごとのメディア上限はボディの上限より厳しいため、実用的なサイズの画像ではまずそちらに達します。
URL はお客様の認証情報なしで解決できる必要があります。Router はサーバー側で取得し、リクエストに呼び出し元の認証情報を含めません。そのため、署名がクエリ文字列に含まれる署名付き URL がサポートされる形式です。/api/assets/{id}/content のような認証必須のエンドポイントは、画像ではなく 401 を Router に返します。その URL はご自身でリクエストし、リダイレクト先の署名付き URL を渡してください。
取得は開かれたインターネットではなく、名前を挙げたホストの集合に限定されます。同じリストは、送信する URL だけでなく各リダイレクトホップにも再適用されます。そのため他のホスト上の URL や、リスト外へリダイレクトする URL は、プロバイダーに接続する前に拒否されます。現時点でそのリストは Comfy 自身のアセット配信のみです。すなわち Comfy のアセットバケット配下の署名付き storage.googleapis.com URL で、これは /api/assets/{id}/content がリダイレクトする形式です。パートナーの CDN や通常の https ホストはリストに含まれません。
2 つの拡張が展開中で、どちらも本日時点ではデフォルトでオフです。これらは 1 つの切り替えの背後で提供され、同時に有効になります。したがって以下の内容はすべて、まだ依存して実装する対象ではなく、今後提供予定のものとして扱ってください。どちらかに依存する前に確認してください。
1 つ目は POST /customers/storage がアップロード先として署名するバケットです。ロールアウトがお使いの環境に到達するまで、そのエンドポイントから得たアップロード URL はここで拒否されます。バケットは Comfy 自身のものでホストも同じであるにもかかわらずです。つまり「Comfy にアップロードしてから URL を渡す」はまだ動作せず、動作するのは /api/assets/{id}/content がリダイレクトする署名付き URL の形式です。
2 つ目は全員一斉ではなくアカウントごとに有効化されます。これらのホストの背後にあるバケットが当社のものではなくお客様のものだからです。上記の切り替えがオンになっていても、サードパーティの受信メディアが有効化されていないアカウントは拒否され、ホストがサポート対象外であるとは告げられず、その旨がそのまま伝えられます。お使いのアカウントでの有効化を Comfy の担当者に依頼してください。さらに、バケットがお客様のもので Router が所有権を主張しない以下のサードパーティのオブジェクトストレージホストも許可されます。Cloudflare R2(<account>.r2.cloudflarestorage.com、pub-<hash>.r2.dev)、Amazon S3(s3.amazonaws.com および s3.<region>.amazonaws.com、パス形式または <bucket>. を前置した形式のいずれか)、Azure Blob Storage(<account>.blob.core.windows.net)、Alibaba Cloud OSS(<bucket>.oss-<region>.aliyuncs.com、oss-accelerate エンドポイントを含む)。これらはあくまでオブジェクトストレージのエンドポイントです。同じプロバイダーのドメイン上の汎用エンドポイント、たとえば Alibaba Function Compute のトリガーはリストに含まれず拒否されます。
照合されるのはホスト名の形式であり、プロバイダーではありません。したがって上であるプロバイダーを挙げたからといって、そのプロバイダーが発行しうるすべての URL が受け入れられるわけではありません。呼び出し元が合理的にたどり着きうる 3 つの紛らわしいケースを明示しておきます。R2 のカスタムドメイン(cdn.example.com)は受け入れられません。Cloudflare は pub-<hash>.r2.dev をレート制限されたデバッグ用ホスト名と位置づけ、本番トラフィックはカスタムドメインに向けるよう案内していますが、カスタムドメインのホスト名には R2 だと識別できる情報が含まれないため、Router は他のホストと区別できず拒否します。<account>.r2.cloudflarestorage.com エンドポイントを署名するか、pub-<hash>.r2.dev 形式を使用してください。S3 の IPv6 dualstack エンドポイント(s3.dualstack.<region>.amazonaws.com)も受け入れられません。通常のリージョン別エンドポイントを使用してください。Azure Blob の代替 DNS ゾーン(<account>.z<N>.blob.storage.azure.net)も同様です。<account>.blob.core.windows.net を使用してください。返される拒否メッセージにはこれらの形式が記載されているので、読みにここへ戻る必要はありません。
上記の <account> と pub-<hash> のプレースホルダーは、通常たどり着く形式を示したものであり、階層の深さの制限ではありません。照合はオブジェクトストレージのドメインサフィックスに対して行われるため、同じ名前空間の下のより深い名前(a.b.pub-<hash>.r2.dev)も受け入れられます。ただし名前空間自体が広がるわけではなく、サフィックスは依然として列挙されたもののいずれかでなければなりません。
以下の例は形状のみを示しています。実際の値には署名用のクエリパラメータも含まれますが、ここでは意図的に省略しています。公開された例は仕様の中に永久に残り、実際の署名は漏洩した認証情報であり、かついずれ機能しなくなるリンクでもあるためです。
各画像は 25 MiB、1 つのリクエストの画像は合計 64 MiB に制限されます。唯一の例外は ideogram/ideogram-4-5 Precise Edit(image を送信する呼び出し)で context_window が利用可能な場合です。そこでは各画像は最大 50 MB(50,000,000 バイト)かつ 67,108,864 ピクセル、1 つのリクエストの画像は合計 128 MiB までです。画像を1つ。呼び出し元に代わって Router が取得する https URL、またはバイト列をインラインで含む
data:image/<format>;base64,<payload> URI のいずれかの形式で指定します。受け付けられる画像形式は png、webp、jpeg で、このセットはプロバイダーに任されるのではなく解決時に強制されます。svg、gif、avif、tiff はここで拒否され、送信した画像が名指しされるため、原因から2ホップ離れたパートナーエラーにはなりません。
URL 形式を推奨します。base64 ペイロードは約4/3に膨らみ、リクエストボディ全体は100 MiB に制限されるため、インライン形式ではソース画像が約75 MB で頭打ちになります。URL ならこれを完全に回避できます。この説明の末尾に記載されている画像ごとおよびリクエストごとのメディア上限はボディの上限よりも厳しいため、実際のサイズの画像ではまずそちらに達します。
URL はあなたの認証情報なしで解決できる必要があります。Router はサーバー側で取得し、リクエストに呼び出し元の認証情報を含めません。そのため、署名がクエリ文字列に入っている presigned URL がサポートされる形式です。/api/assets/{id}/content のような認証が必要なエンドポイントは Router に画像ではなく401を返します。その URL を自分でリクエストし、リダイレクト先の署名付き URL を渡してください。
取得は開かれたインターネットではなく、名前を挙げたホスト群に限定されます。同じリストは、送信した URL だけでなくすべてのリダイレクトホップにも再適用されます。したがって、それ以外のホストの URL や、リスト外へリダイレクトする URL は、プロバイダーに接触する前に拒否されます。現在そのリストは Comfy 自身のアセット配信のみです。すなわち Comfy のアセットバケット配下の署名付き storage.googleapis.com URL で、これは /api/assets/{id}/content がリダイレクトする形式です。パートナー CDN や通常の https ホストはリストにありません。
2つの拡張が段階的に展開中で、どちらも本日時点ではデフォルトでオフです。これらは1つの切り替えの背後で提供され、同時に有効化されます。したがって、以下はすべて今後提供予定のものとして扱い、まだ依存して実装しないでください。どちらかに依存する前に確認してください。
1つ目は POST /customers/storage がアップロード先として署名するバケットです。展開があなたの環境に届くまで、そのエンドポイントから得たアップロード URL はここで拒否されます。バケットは Comfy 自身のものでホストも同じであってもです。そのため「Comfy にアップロードしてから URL を渡す」はまだ動作せず、動作するのは /api/assets/{id}/content がリダイレクトする署名付き URL です。
2つ目は全員一斉ではなくアカウント単位で有効化されます。これらのホストの背後にあるバケットは当社のものではなくあなたのものだからです。上記の切り替えがオンになっても、サードパーティのインバウンドメディアが有効化されていないアカウントは拒否され、ホストが非対応だとは言われず、その旨がそのまま伝えられます。Comfy の担当者にアカウントでの有効化を依頼してください。これはさらに、以下のサードパーティのオブジェクトストレージホストを許可します。そこではバケットはあなたのものであり、Router は所有権を主張しません: Cloudflare R2 (<account>.r2.cloudflarestorage.com、pub-<hash>.r2.dev)、Amazon S3 (s3.amazonaws.com および s3.<region>.amazonaws.com、パススタイルまたは <bucket>. プレフィックス形式のいずれか)、Azure Blob Storage (<account>.blob.core.windows.net)、Alibaba Cloud OSS (<bucket>.oss-<region>.aliyuncs.com、oss-accelerate エンドポイントを含む)。これらはオブジェクトストレージのエンドポイントに限定されます。同じプロバイダーのドメイン上の汎用エンドポイント、たとえば Alibaba Function Compute のトリガーはリストになく拒否されます。
一致判定の対象はプロバイダーではなくホスト名の形式です。したがって上でプロバイダーを挙げたからといって、そのプロバイダーが発行しうるすべての URL が受け入れられるわけではありません。呼び出し元がそれぞれの形で到達しうる3つの紛らわしいケースを明記しておきます。R2 のカスタムドメイン (cdn.example.com) は受け入れられません。Cloudflare は pub-<hash>.r2.dev をレート制限のあるデバッグ用ホスト名と文書化し、本番トラフィックはカスタムドメインに向けるよう案内していますが、カスタムドメインのホスト名には R2 だと分かる情報がないため、Router は他のホストと区別できず拒否します。<account>.r2.cloudflarestorage.com エンドポイントに署名するか、pub-<hash>.r2.dev 形式を使用してください。S3 の IPv6 dualstack エンドポイント (s3.dualstack.<region>.amazonaws.com) も受け入れられません。通常のリージョナルエンドポイントを使用してください。Azure Blob の代替 DNS ゾーン (<account>.z<N>.blob.storage.azure.net) も同様です。<account>.blob.core.windows.net を使用してください。返される拒否メッセージにも同じ形式が記載されているため、ここに戻って読む必要はありません。
上記の <account> と pub-<hash> のプレースホルダーは通常たどり着く形式を示しているのであり、階層の深さの制限ではありません。マッチングはオブジェクトストレージのドメインサフィックスに対して行われるため、同じ名前空間のより深い名前 (a.b.pub-<hash>.r2.dev) も受け入れられます。ただしそれによって名前空間自体が広がるわけではありません。サフィックスは依然として列挙されたもののいずれかでなければなりません。
以下の例は形状のみを示しています。実際の値には署名のクエリパラメータも含まれますが、公開された例は仕様に永久に残り、実際の署名は漏洩した認証情報であると同時に機能しなくなるリンクでもあるため、ここでは意図的に省略しています。
各画像は25 MiB、1つのリクエストの画像は合計64 MiB が上限です。唯一の例外は ideogram/ideogram-4-5 Precise Edit(image を送信する呼び出し)で context_window が利用可能な場合です。その場合、各画像は最大50 MB(50,000,000バイト)かつ67,108,864ピクセル、1つのリクエストの画像は合計最大128 MiB です。品質ティア。デフォルトは medium。very_low は最大 2K でレンダリングします。課金レートは品質、リクエストが編集かどうか、出力が 2K を超えるかどうかによって異なります。指定可能な値:
very_low, low, medium, high生成専用。auto(デフォルト)は約 2K を選択します。WIDTHxHEIGHT は 32 ピクセルのグリッド上で指定し、最大 16,777,216 ピクセル、各辺は最大 8192、比率は 6:1 までです。または source を指定すると
images の最初の画像に合わせます。GET /v2/models/ideogram/ideogram-4-6/openapi.json で提供するものから生成済みです。これはリクエストがプロバイダーに到達する前に呼び出しを検証するのと同じドキュメントです。
出力
例
入力
出力
出荷前の確認
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 が現在対応していないことと、代替手段。