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

# 结合 Comfy Router 使用 Ideogram 4.0

> 通过 Comfy Router 以 HTTP 方式调用 Ideogram 4.0 生成图像的 Python、TypeScript 和 cURL 代码片段，以及请求字段与返回结果的结构

Ideogram 4.0 的 API 参考。Ideogram 4.0 是 Ideogram 的文生图模型，可在生成的图像中渲染清晰可读的文字。

## 快速入门

在[你的 Comfy 工作区](https://platform.comfy.org/profile/api-keys?onboarding=router)中创建密钥，并将其导出为 `COMFY_API_KEY`。Python 和 TypeScript 片段使用 Comfy SDK（`pip install comfy-sdk` 和 `npm install @comfyorg/sdk`）；cURL 片段是通过原始 HTTP 发出的相同调用。

**模型 ID：** `ideogram/ideogram-v4`

**端点：** `POST https://api.comfy.org/v2/models/ideogram/ideogram-v4`

<Tabs defaultTabIndex={1}>
  <Tab title="等待结果">
    <CodeGroup>
      ```python Python theme={null}
      import asyncio
      from comfy_sdk import AsyncComfy

      # 从环境变量中读取 COMFY_API_KEY。
      # SDK 会自动创建幂等键，并在自动重试时复用它。
      async def main():
          async with AsyncComfy() as client:
              result = await client.models.run(
                  "ideogram/ideogram-v4",
                  {
                      "text_prompt": "a single red maple leaf on a plain white background, studio lighting",
                      "resolution": "1024x1024",
                      "rendering_speed": "DEFAULT",
                  },
              )

          print("image:", result["data"][0]["url"])

      asyncio.run(main())
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // 从环境变量中读取 COMFY_API_KEY。
      // SDK 会自动创建幂等键，并在自动重试时复用它。
      type Result = { data: { url: string }[] };
      const result = await comfy.models.run<Result>("ideogram/ideogram-v4", {
        text_prompt: "a single red maple leaf on a plain white background, studio lighting",
        resolution: "1024x1024",
        rendering_speed: "DEFAULT",
      });
      if (result.kind !== "json") throw new Error("expected a JSON result");

      console.log("image:", result.data.data[0].url);
      ```

      ```bash cURL theme={null}
      curl https://api.comfy.org/v2/models/ideogram/ideogram-v4 \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"text_prompt\": \"a single red maple leaf on a plain white background, studio lighting\", \"resolution\": \"1024x1024\", \"rendering_speed\": \"DEFAULT\"}"
      ```
    </CodeGroup>
  </Tab>

  <Tab title="稍后排队并收集">
    相同的请求体，发送至 `POST https://api.comfy.org/v2/models/ideogram/ideogram-v4/requests`。请求一经接纳，Router 便会以 `201` 返回 `request_id`，结果准备就绪后即可收集，可以在当前进程，也可以在另一个进程中收集。[队列投递](/zh/development/comfy-router/queue) 会逐步讲解状态、取消和收集。

    <CodeGroup>
      ```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-v4",
                  {
                      "text_prompt": "a single red maple leaf on a plain white background, studio lighting",
                      "resolution": "1024x1024",
                      "rendering_speed": "DEFAULT",
                  },
              )
              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("image:", result["data"][0]["url"])

      asyncio.run(main())
      ```

      ```typescript TypeScript theme={null}
      import { comfy } from "@comfyorg/sdk";

      // 从环境变量中读取 COMFY_API_KEY。
      // 每次 submit() 调用都会生成自己的 Idempotency-Key，并在自动重试时复用它。
      type Result = { data: { url: string }[] };
      const handle = await comfy.models.submit<Result>("ideogram/ideogram-v4", {
        text_prompt: "a single red maple leaf on a plain white background, studio lighting",
        resolution: "1024x1024",
        rendering_speed: "DEFAULT",
      });
      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();
      if (result.kind !== "json") throw new Error("expected a JSON result");

      console.log("image:", result.data.data[0].url);
      ```

      ```bash cURL theme={null}
      # 1. 提交。Router 以 201 返回 request_id、status_url、response_url 和 cancel_url。
      curl https://api.comfy.org/v2/models/ideogram/ideogram-v4/requests \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Idempotency-Key: $(uuidgen)" \
        -H "Content-Type: application/json" \
        -d "{\"text_prompt\": \"a single red maple leaf on a plain white background, studio lighting\", \"resolution\": \"1024x1024\", \"rendering_speed\": \"DEFAULT\"}"

      # 2. 轮询直到状态为 COMPLETED，每个响应都会指明需要等待的 Retry-After 秒数。
      REQUEST_ID="<request_id from the 201 body>"
      curl -i https://api.comfy.org/v2/models/ideogram/ideogram-v4/requests/$REQUEST_ID/status \
        -H "X-API-Key: $COMFY_API_KEY"

      # 3. 收集。返回 200 时携带模型的原生输出，仍在运行时返回 202 及状态正文。
      curl https://api.comfy.org/v2/models/ideogram/ideogram-v4/requests/$REQUEST_ID \
        -H "X-API-Key: $COMFY_API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Schema

### 输入

<ParamField body="enable_copyright_detection" type="boolean">
  选择开启生成后版权检测（Hive 相似度和标识检查）。
</ParamField>

<ParamField body="json_prompt" type="object">
  结构化的 V4 提示词。会禁用 Magic Prompt；直接使用该内容。text\_prompt 或 json\_prompt 必须且只能提供其中一个。
</ParamField>

<ParamField body="rendering_speed" type="string" default="&#x22;DEFAULT&#x22;">
  渲染速度设置，用于控制生成速度与质量之间的权衡

  可选值：`DEFAULT`、`TURBO`、`QUALITY`
</ParamField>

<ParamField body="resolution" type="string">
  输出分辨率，格式为 WIDTHxHEIGHT。省略该参数则让模型自行选择宽高比。支持的 2K 取值：2048x2048、1440x2880、2880x1440、1664x2496、2496x1664、1792x2240、2240x1792、1440x2560、2560x1440、1600x2560、2560x1600、1728x2304、2304x1728、1296x3168、3168x1296、1152x2944、2944x1152、1248x3328、3328x1248、1280x3072、3072x1280。
</ParamField>

<ParamField body="text_prompt" type="string">
  自然语言提示词。会自动启用 Magic Prompt。text\_prompt 或 json\_prompt 必须且只能提供其中一个。
</ParamField>

内容根据 Router 在 `GET /v2/models/ideogram/ideogram-v4/openapi.json` 处提供的 schema 生成，该文档与请求到达提供商之前用于校验调用的文档相同。

### 输出

<ResponseField name="created" type="string (date-time)">
  生成创建时的时间戳。

  格式：`date-time`
</ResponseField>

<ResponseField name="data" type="object[]">
  已生成图像信息的数组。
</ResponseField>

<ResponseField name="data[].is_image_safe" type="boolean">
  指示该图像是否被视为安全。
</ResponseField>

<ResponseField name="data[].prompt" type="string">
  用于生成此图像的提示词。
</ResponseField>

<ResponseField name="data[].resolution" type="string">
  已生成图像的分辨率（例如 '1024x1024'）。
</ResponseField>

<ResponseField name="data[].seed" type="integer">
  此次生成使用的种子值。
</ResponseField>

<ResponseField name="data[].style_type" type="string">
  生成所使用的风格类型（例如 'REALISTIC'、'ANIME'）。
</ResponseField>

<ResponseField name="data[].url" type="string">
  已生成图像的 URL。
</ResponseField>

## 示例

### 输入

```json theme={null}
{
  "text_prompt": "a single red maple leaf on a plain white background, studio lighting",
  "resolution": "1024x1024",
  "rendering_speed": "DEFAULT"
}
```

### 输出

```json theme={null}
{
  "response_type": "url",
  "created": "2026-08-27T21:00:00Z",
  "data": [
    {
      "url": "https://.../image.png",
      "prompt": "a single red maple leaf on a plain white background, studio lighting",
      "resolution": "1024x1024",
      "seed": 1234567890,
      "is_image_safe": true
    }
  ]
}
```

该 URL 是临时链接。如果你需要保留图像，请及时下载。

## 发布前须知

SDK 会生成 `Idempotency-Key` 并在自动重试中复用它。手动重试时，请复用原始 key。Router 最长可保持连接 10 分钟。

请求失败时，Router 会发送 `X-Comfy-Error-Type` 响应头说明原因。`422` 表示 Router 在调用提供商之前就拒绝了输入，`413` 表示请求体超出了 Router 可接受的大小。已生成的资源请及时下载，因为[结果 URL 会过期](/zh/development/comfy-router/reference#结果资产)。

上文任何字段描述中提到的尺寸限制，都是提供商对该字段自身的限定，引自提供商的规范。Router 会对整个请求体另行设置上限，base64 编码的媒体内容也计入其中：参见[请求体大小](/zh/development/comfy-router/limitations)。

本页记录的是通过 Comfy Router 调用的某一个合作伙伴模型。同一个 `comfy-sdk` / `@comfyorg/sdk` 包还提供第二个客户端，用于在 Comfy Cloud 上运行完整的 ComfyUI 工作流图：`Comfy(api_key=...)` / `new Comfy({ apiKey })`，并带有 `client.workflows`、`client.assets` 和 `client.jobs`。请参阅 [Comfy SDKs](/zh/development/api-development/sdks)。

<CardGroup cols={3}>
  <Card title="请求头" icon="list" href="/zh/development/comfy-router/headers">
    身份验证、幂等性、请求 ID、错误分类、重试节奏、消费限额。
  </Card>

  <Card title="使用 Router API" icon="code" href="/zh/development/comfy-router/api">
    模型发现、验证错误、重试与计费。
  </Card>

  <Card title="限制" icon="triangle-exclamation" href="/zh/development/comfy-router/limitations">
    Router 目前不支持的功能，以及替代方案。
  </Card>
</CardGroup>