将 Ideogram 4.5 与 Comfy Router 配合使用
通过 Comfy Router 调用 ideogram/ideogram-4-5：endpoint、请求结构以及 Router 返回的响应。
将 Ideogram 4.5 与 Comfy Router 配合使用
通过 Comfy Router 调用 ideogram/ideogram-4-5：endpoint、请求结构以及 Router 返回的响应。
ideogram/ideogram-4-5 的 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-5
端点： POST https://api.comfy.org/v2/models/ideogram/ideogram-4-5
[tab] 等待结果 ``python Python theme={null} from comfy_sdk import Comfy # 从环境变量中读取 COMFY_API_KEY。 # SDK 会自动创建幂等键，并在自动重试时复用它。 with Comfy() as client: result = client.models.run( "ideogram/ideogram-4-5", { "prompt": "A poster for a jazz festival, bold typography, warm colours", "quality": "low", }, ) print(result)``typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // SDK 会自动创建幂等键，并在自动重试时复用它。 const { data } = await comfy.models.run("ideogram/ideogram-4-5", { prompt: "A poster for a jazz festival, bold typography, warm colours", quality: "low", }); console.log(data);``bash cURL theme={null} curl https://api.comfy.org/v2/models/ideogram/ideogram-4-5 \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"prompt\": \"A poster for a jazz festival, bold typography, warm colours\", \"quality\": \"low\"}"``
[tab] 排队并稍后收集 相同的请求体，发送到POST https://api.comfy.org/v2/models/ideogram/ideogram-4-5/requests。请求一旦被接纳，Router 就会以201返回request_id，结果就绪后即可从当前进程或其他进程收集。队列投递 介绍了状态、取消与结果收集的完整流程。 ``python Python theme={null} import asyncio from comfy_sdk import AsyncComfy # 从环境变量中读取 COMFY_API_KEY。 # 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 async def main(): async with AsyncComfy() as client: handle = await client.models.submit( "ideogram/ideogram-4-5", { "prompt": "A poster for a jazz festival, bold typography, warm colours", "quality": "low", }, ) print("request_id:", handle.request_id) # 配合模型 ID，就是另一个进程所需的全部信息 # 轮询直到请求完成，等待服务器指定的 Retry-After 时长。 async for update in handle.iter_events(): print(update.status, update.queue_position) # 提供商返回的原始载荷，与 models.run() 返回的值相同。 # 失败或已取消的请求会在这里抛出 Router 的类型化错误。 result = await handle.get() print(result) asyncio.run(main())``typescript TypeScript theme={null} import { comfy } from "@comfyorg/sdk"; // 从环境变量中读取 COMFY_API_KEY。 // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。 const handle = await comfy.models.submit("ideogram/ideogram-4-5", { prompt: "A poster for a jazz festival, bold typography, warm colours", quality: "low", }); console.log("requestId:", handle.requestId); // 配合模型 ID，就是另一个进程所需的全部信息 // 轮询直到请求完成，等待服务器指定的 Retry-After 时长。 for await (const update of handle.events()) { console.log(update.status, update.queuePosition); } // 与 models.run() 返回的结果相同。失败或已取消的请求会在这里 reject。 const result = await handle.get(); console.log(result.data);``bash cURL theme={null} # 1. 提交。Router 会以 201 返回 request_id、status_url、response_url 和 cancel_url。 curl https://api.comfy.org/v2/models/ideogram/ideogram-4-5/requests \ -H "X-API-Key: $COMFY_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d "{\"prompt\": \"A poster for a jazz festival, bold typography, warm colours\", \"quality\": \"low\"}" # 2. 轮询直到 status 为 COMPLETED，每次响应都会指定需要等待的 Retry-After 秒数。 REQUEST_ID="<request_id from the 201 body>" curl -i https://api.comfy.org/v2/models/ideogram/ideogram-4-5/requests/$REQUEST_ID/status \ -H "X-API-Key: $COMFY_API_KEY" # 3. 收集。200 返回模型的原始输出，仍在运行时 202 返回状态体。 curl https://api.comfy.org/v2/models/ideogram/ideogram-4-5/requests/$REQUEST_ID \ -H "X-API-Key: $COMFY_API_KEY"``
Schema
输入
context\_window string
仅适用于 Precise Edit；需要 image。编辑所作用的源图像区域，因此可以在超大图像的一处进行编辑，然后以完整尺寸返回图像，其余部分保持不变。none（默认值）会编辑整张图像。auto 会围绕 mask 适配出一个区域，并且需要提供 mask。否则请发送 y_min,x_min,y_max,x_max，以四个非负整数像素边界表示，其中 y_max 大于 y_min 且 x_max 大于 x_min，每边至少 256 像素，宽高比在 1:6 与 6:1 之间，面积至多 4,194,304 像素。不带 image 的请求若使用 none 以外的值，会被拒绝。context_window 仅在上下文窗口门控启用时才会被接受；在未启用的情况下，任何 none 以外的值都会以 422 被拒绝。
enable\_copyright\_detection boolean
选择启用生成后的版权检测。
image string
一张图像，可以是 Router 代表调用方获取的 https URL，也可以是内联携带字节的 data:image/<format>;base64,<payload> URI。接受的图像类型为 png、webp 和 jpeg，并且该集合在解析时即强制执行，而不是留给提供商处理：svg、gif、avif 或 tiff 会在这里被拒绝，并指明你发送的图像，而不是变成距根因两跳的合作伙伴错误。 优先使用 URL 形式。base64 载荷大约会膨胀 4/3，而整个请求体的上限为 100 MiB，因此内联形式的上限接近 75 MB 的源图像；URL 则完全避开这一点。本描述末尾列出的单图像和单请求媒体上限比请求体上限更严格，因此对于任何实际尺寸的图像，你会先碰到这些上限。 该 URL 必须在不使用你的凭据的情况下解析。Router 在服务器端获取它，并且不会随请求发送调用方凭据，因此支持的形式是预签名 URL，即签名位于查询字符串中的 URL。像 /api/assets/{id}/content 这样的已认证端点会向 Router 返回 401，而不是返回图像；请自行请求该 URL，并传入它重定向到的已签名 URL。 获取范围限于一组指定主机，而不是整个开放互联网，并且同一列表不仅应用于你发送的 URL，也会重新应用于每一次重定向跳转：因此，位于任何其他主机的 URL，或重定向到列表之外的 URL，都会在联系任何提供商之前被拒绝。目前该列表仅包含 Comfy 自己的资产分发：Comfy 资产桶下已签名的 storage.googleapis.com URL，这正是 /api/assets/{id}/content 重定向到的形式。合作伙伴 CDN 或普通 https 主机不在列表中。 两项放宽正在逐步推出，且目前都默认关闭。它们通过同一个切换发布并一起启用，因此请将以下所有内容视为即将推出，而不是现在就可以依据其进行开发：在依赖其中任何一项之前，请先询问。 第一项是 POST /customers/storage 将你的上传签名到的那个桶。在推广到达你的环境之前，来自该端点的上传 URL 会在此处被拒绝，即使该桶属于 Comfy 自己且主机相同：因此，“上传到 Comfy，然后传入 URL”目前并不起作用，可行的形式是 /api/assets/{id}/content 重定向到的已签名 URL。 第二项按账户启用，而不是一次性对所有人启用，因为这些主机背后的桶属于你而不是我们：即使上面的切换已打开，未启用第三方入站媒体的账户也会被拒绝，并且会明确告知这一点，而不是告知该主机不受支持。请联系你的 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 都会被接受，而且有三种接近但不匹配的形式值得直接说明，因为调用方完全可能提交其中任意一种。R2 自定义域（cdn.example.com）不被接受：Cloudflare 将 pub-<hash>.r2.dev 记录为限速的调试主机名，并把生产流量改为指向自定义域；但自定义域的主机名中没有任何可标识其为 R2 的信息，因此 Router 无法将其与任何其他主机区分开来，并会拒绝它：请对 <account>.r2.cloudflarestorage.com 端点进行预签名，或使用 pub-<hash>.r2.dev 形式。S3 的 IPv6 双栈端点（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，单个请求中的图像总计上限为 64 MiB。唯一例外是 ideogram/ideogram-4-5 Precise Edit（即发送 image 的调用），此时 context_window 可用：每张图像最大可达 50 MB（50,000,000 字节）和 67,108,864 像素，单个请求中的图像总计最大可达 128 MiB。
images string[]
用于生成操作的可选源图像。第一张是主来源，其余是参考图像。最多五张，或在使用遮罩时最多四张。
magic\_prompt string
仅适用于生成。用于文生图的提示词重写。支持的值为 auto、on 和 off。默认值为 auto。
mask string
一张图像，形式可以是 Router 代表调用方获取的 https URL，也可以是携带内联字节的 data:image/<format>;base64,<payload> URI。接受的图像类型为 png、webp 和 jpeg，并且该集合会在解析时强制校验，而不是留给提供商处理；svg、gif、avif 或 tiff 会在这里被拒绝，并指明你发送的图像，而不是变成在离原因两步之外才出现的合作伙伴错误。 优先使用 URL 形式。base64 载荷大约会膨胀 4/3，而整个请求体上限为 100 MiB，因此内联形式的上限约为 75 MB 的源图像；URL 则完全绕开这一点。本描述末尾所述的每张图像与每个请求的媒体上限比请求体上限更严格，因此对于任何实际尺寸的图像，你会先遇到它们。 该 URL 必须在不携带你的凭证的情况下完成解析。Router 会在服务器端获取它，并且不会随请求发送任何调用方凭证，因此受支持的形式是预签名 URL，即签名位于查询字符串中的 URL。诸如 /api/assets/{id}/content 这类需要认证的端点会向 Router 返回 401，而不是返回图像；请自行请求该 URL，并传入它重定向到的已签名 URL。 获取操作被限制在一组指定的主机内，而不是开放互联网，并且同一列表会重新应用于你发送的 URL 以及每一次重定向跳转；因此，任何其他主机上的 URL，或会重定向到列表之外的 URL，都会在联系任何提供商之前被拒绝。目前该列表仅包含 Comfy 自己的资产分发：Comfy 资产存储桶下已签名的 storage.googleapis.com URL，也就是 /api/assets/{id}/content 会将你重定向到的形式。合作伙伴 CDN 或普通 https 主机不在该列表中。 两项放宽正在陆续推出，而且目前默认都处于关闭状态。它们由同一个切换开关控制并一起启用，因此请将下面所有内容视为即将推出，而不要现在就基于它进行开发；在依赖其中任何一项之前请先咨询。 第一项是 POST /customers/storage 为你的上传签名后写入的存储桶。在推出覆盖到你的环境之前，来自该端点的上传 URL 在此会被拒绝，即使该存储桶属于 Comfy 自己且主机相同也是如此；因此“先上传到 Comfy，再传入 URL”的方式目前还不可用，而可用的形式是 /api/assets/{id}/content 重定向到的已签名 URL。 第二项是按账户启用，而不是一次性对所有人生效，因为这些主机背后的存储桶属于你而不是我们：即使上面的切换开关已打开，未启用第三方入站媒体的账户仍会被拒绝，并会明确告知这一点，而不是告知该主机不受支持。请联系你的 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 端点）。这些明确是对象存储端点：同一提供商域名下的通用端点，例如阿里云函数计算触发器，不在该列表中，会被拒绝。 匹配的是主机名形式，而不是提供商；因此，上面列出某个提供商并不意味着该提供商能够签发的每个 URL 都会被接受，并且有三种近似但不受支持的形式值得直接说明，因为调用方完全可能带着其中任何一种形式到来。R2 自定义域名（cdn.example.com）不被接受：Cloudflare 将 pub-<hash>.r2.dev 记录为限速的调试主机名，并改为将生产流量指向自定义域名；但自定义域名的主机名中没有任何信息能标识它是 R2，因此 Router 无法将其与任何其他主机区分开来，并会拒绝它。请对 <account>.r2.cloudflarestorage.com 端点进行预签名，或使用 pub-<hash>.r2.dev 形式。S3 的 IPv6 双栈端点（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，单个请求的图像总量上限为 64 MiB。唯一的例外是 ideogram/ideogram-4-5 Precise Edit（即发送 image 的调用），此时 context_window 可用：在该情况下每张图像最大可达 50 MB（50,000,000 字节）和 67,108,864 像素，单个请求的图像总量上限为 128 MiB。
num\_images integer (default: 1)
要返回的图像数量。每张都会计费。
范围：1 到 8
prompt string required
图像的指令或描述，1 到 10,000 个字符。
quality string
质量档位，同时也是计费费率。有来源图像时：very\_low、low、medium 或 high（默认 medium）。无来源图像时：low、medium 或 high（默认 high）；文生图请求中的 very\_low 会被拒绝。
可选值：very_low、low、medium、high
reference\_images string[]
Precise Edit 的可选参考图像；需要 image。最多四张，带遮罩时最多三张。
seed integer
用于可复现结果的种子。
范围：0 到 2147483647
size string
仅生成时可用。输出尺寸。auto（默认）、source（需要图像）或 WIDTHxHEIGHT。发送遮罩时请省略此项；同时设置两者的请求会被拒绝。
根据 Router 在 GET /v2/models/ideogram/ideogram-4-5/openapi.json 提供的 schema 生成，这也是它在请求到达提供商之前用来校验调用的同一份文档。
输出
data object[]
已生成的图像。
data\[].is\_image\_safe boolean
指示图像是否被视为安全。仅使用此值为 true 的图像。
data\[].prompt string
用于生成此图像的提示词。
data\[].resolution string
已生成图像的分辨率。
data\[].seed integer
用于此图像的种子。
data\[].url string
已生成图像的 URL。
generation\_id string
生成任务的标识符。
seed integer
用于该次生成的种子。
示例
输入
{
"prompt": "A poster for a jazz festival, bold typography, warm colours",
"quality": "low"
}
输出
{
"data": [
{
"is_image_safe": true,
"prompt": "A poster for a jazz festival, bold typography, warm colours",
"resolution": "2048x2048",
"seed": 918273645,
"url": "https://example.invalid/ideogram/ideogram-4-5/generated.png"
}
],
"generation_id": "gen_0123456789",
"seed": 918273645
}
发布前须知
SDK 会生成 Idempotency-Key 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。
请求失败时，Router 会发送 X-Comfy-Error-Type 响应头说明原因。422 表示 Router 在调用提供商之前就拒绝了输入，413 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为结果 URL 会过期。
上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见请求体大小。
本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 comfy-sdk / @comfyorg/sdk 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：Comfy(api_key=...) / new Comfy({ apiKey })，并带有 client.workflows、client.assets 和 client.jobs。请参阅 Comfy SDKs。
[card] 请求头 身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
[card] 使用 Router API 模型发现、验证错误、重试与计费。
[card] 限制 Router 目前不支持的功能，以及替代方案。