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

# Ideogram V4.6

> Ideogram 4.6 API 根据文本提示词一次生成最多 8 张图像，图上文字渲染准确，提供四档质量、每边最高 4096 像素的自定义尺寸、透明背景和随机种子。

> [!TIP]
>
> 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。
> 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.poyo.ai/zh/api-manual/task-management/status.md)接口获取结果。

Ideogram 4.6 API 将 Ideogram 最新的图像模型接入 PoYo。它适合制作海报、Logo、包装、社交媒体图片，以及任何需要图上文字准确无误的图像。Ideogram 4.6 API 接收一段提示词，返回 1 到 8 张图像，可选四档质量、宽高比预设或每边最高 4096 像素的精确尺寸，并支持透明背景。如需修改已有图像，请使用 [Ideogram 4.6 Edit API](https://docs.poyo.ai/zh/api-manual/image-series/ideogram-v4-6-edit.md)。

## Ideogram 4.6 API 模型

* **ideogram-v4.6** — 文生图，支持质量、尺寸、背景和随机种子控制
* **ideogram-v4.6-edit** — 图像编辑，支持蒙版和参考图。参见 [Ideogram V4.6 Edit](https://docs.poyo.ai/zh/api-manual/image-series/ideogram-v4-6-edit.md)

## Ideogram 4.6 API 功能

* **图上文字**：在提示词中写出要显示的原文，例如标题或招牌文字，模型会把它渲染到图像上。
* **四档质量**：`very_low` 适合快速出草图，另有 `low`、`medium`（默认）和 `high`。
* **最高 4K 尺寸**：可选 `auto`、六种宽高比预设，或每边 256 到 4096 像素的自定义 `WIDTHxHEIGHT`。
* **透明背景**：将 `background` 设为 `transparent`，即可得到带 alpha 通道的图像，适合贴纸、图标和 Logo。
* **批量与种子**：每次请求最多生成 8 张图像，设置 `seed` 可复现结果。

## 必填参数

* `prompt` (string)：描述图像的提示词，1–10,000 个字符，必须包含非空白文本。需要原样出现在图上的文字，请用引号括起来。

## 可选参数

* `size` (string)：`auto`、`1:1`、`1:1 HD`、`4:3`、`3:4`、`16:9`、`9:16` 或自定义 `WIDTHxHEIGHT`。默认为 `auto`。参见[尺寸](#尺寸)。
* `quality` (string)：`very_low`、`low`、`medium` 或 `high`。默认为 `medium`。`very_low` 只适用于不超过 4,194,304 像素（面积 2048×2048）的输出。
* `n` (integer)：图像数量，`1` 到 `8`。默认为 `1`。
* `background` (string)：`transparent` 或 `opaque`。`transparent` 返回带 alpha 通道的图像；`opaque` 强制使用实色背景。不传则由模型决定。
* `seed` (integer)：随机种子，`0` 到 `2147483647`。不传则自动选取。
* `callback_url` (string)：可选的 Webhook URL，用于任务完成通知。放在请求顶层，不要放进 `input`。

Ideogram 4.6 API 的 `input` 只接受以上字段。传入其他字段会返回 `unsupported fields` 错误。

## 尺寸

| `size` | 输出 |
| - | - |
| `auto`（默认） | 由模型选择约 2K 的尺寸 |
| `1:1` | 512×512 |
| `1:1 HD` | 1024×1024 |
| `4:3` | 1024×768 |
| `3:4` | 768×1024 |
| `16:9` | 1024×576 |
| `9:16` | 576×1024 |
| `WIDTHxHEIGHT` | 按填写的宽高输出 |

自定义尺寸使用小写 `x`，例如 `2048x1152`。宽和高都必须在 `256` 到 `4096` 像素之间且为 `32` 的倍数，宽高比须在 `1:6` 到 `6:1` 之间。Ideogram 4.5 API 接受、但不是 32 倍数的尺寸（例如 `1296x3168`）会被拒绝。

## 输出

任务状态为 `finished` 时，`files` 中每张生成的图像对应一项，包含 `file_url` 和 `file_type: image`。`background` 设为 `transparent` 时，图像带 alpha 通道。

## Ideogram 4.6 API 示例

将下面的 Ideogram 4.6 API 请求发送到 `POST /api/generate/submit`，并在 `Authorization` 请求头中携带 API Key。

### 文生图

```json theme={"dark"}
{
  "model": "ideogram-v4.6",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A colorful storefront with a neon sign reading \"HELLO\""
  }
}
```

该请求使用默认设置（`auto`、`medium`、一张图）。

### 4K 尺寸海报

```json theme={"dark"}
{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A minimalist poster titled \"SUMMER JAZZ NIGHTS\", bold typography",
    "size": "2048x3072",
    "quality": "high",
    "n": 2
  }
}
```

`2048x3072` 为 6,291,456 像素，超过 4,194,304 像素，因此该尺寸不能使用 `very_low`。

### 透明背景贴纸

```json theme={"dark"}
{
  "model": "ideogram-v4.6",
  "input": {
    "prompt": "A flat sticker of a smiling coffee cup",
    "size": "1:1 HD",
    "quality": "low",
    "background": "transparent",
    "seed": 42
  }
}
```

## 注意事项

* `very_low` 与超过 4,194,304 像素的自定义尺寸同时使用时会被拒绝，错误信息为 "very\_low quality supports sizes up to 2048x2048 pixels in area (4,194,304 pixels)"。
* `n` 必须为整数，字符串和布尔值会被拒绝。
* 与 Ideogram 4.5 相同，Ideogram 4.6 API 始终开启提示词扩展。
* 生成的图像文件在创建后 3 天内可访问，请及时下载保存。
* 响应返回 `task_id`，请通过查询任务状态获取生成的图像。


## OpenAPI

````yaml zh/api-manual/image-series/ideogram-v4-6.json POST /api/generate/submit
openapi: 3.1.0
info:
  title: PoYo AI - Ideogram V4.6 API
  description: >-
    Ideogram 4.6 API 根据文本提示词一次生成最多 8 张图像，图上文字渲染准确，提供四档质量、每边最高 4096
    像素的自定义尺寸、透明背景和随机种子。
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Ideogram V4.6
      summary: 提交 Ideogram V4.6 任务
      description: Ideogram 4.6 API 文生图，提供四档质量、每边最高 4096 像素的尺寸、透明背景和随机种子。
      operationId: submit_ideogram_v4_6
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-image:
                summary: 文生图
                value:
                  model: ideogram-v4.6
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: A colorful storefront with a neon sign reading "HELLO"
              poster-4k:
                summary: 4K 尺寸海报
                value:
                  model: ideogram-v4.6
                  input:
                    prompt: >-
                      A minimalist poster titled "SUMMER JAZZ NIGHTS", bold
                      typography
                    size: 2048x3072
                    quality: high
                    'n': 2
              transparent-sticker:
                summary: 透明背景贴纸
                value:
                  model: ideogram-v4.6
                  input:
                    prompt: A flat sticker of a smiling coffee cup
                    size: 1:1 HD
                    quality: low
                    background: transparent
                    seed: 42
      responses:
        '200':
          description: 任务提交成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          description: 请求参数无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权，API Key 无效
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubmitRequest:
      type: object
      required:
        - model
        - input
      additionalProperties: false
      properties:
        model:
          type: string
          enum:
            - ideogram-v4.6
          description: Ideogram 4.6 文生图模型标识。
        callback_url:
          type: string
          format: uri
          description: 可选的 Webhook URL，任务完成或失败时通知。
        input:
          type: object
          additionalProperties: false
          required:
            - prompt
          description: 根据提示词生成 1-8 张图像。
          properties:
            prompt:
              type: string
              minLength: 1
              maxLength: 10000
              pattern: \S
              description: 必填。描述图像的提示词，1-10,000 个字符，必须包含非空白文本。需要原样出现在图上的文字，请用引号括起来。
            size:
              type: string
              default: auto
              pattern: ^(auto|1:1|1:1 HD|4:3|3:4|16:9|9:16|[0-9]+x[0-9]+)$
              examples:
                - auto
                - 1:1 HD
                - '16:9'
                - 2048x2048
              description: >-
                auto（默认，由模型选择约 2K 的尺寸）、1:1（512x512）、1:1
                HD（1024x1024）、4:3、3:4、16:9、9:16，或使用小写 x 的自定义
                WIDTHxHEIGHT。自定义尺寸每边须为 256-4096 像素且为 32 的倍数，宽高比在 1:6 到 6:1 之间。超过
                4,194,304 像素的自定义尺寸不支持 very_low。
            quality:
              type: string
              enum:
                - very_low
                - low
                - medium
                - high
              default: medium
              description: 输出质量，默认为 medium。very_low 只适用于不超过 4,194,304 像素（面积 2048x2048）的输出。
            'n':
              type: integer
              minimum: 1
              maximum: 8
              default: 1
              description: 输出图像数量，1-8，默认为 1。必须为整数。
            background:
              type: string
              enum:
                - transparent
                - opaque
              description: 可选。transparent 返回带 alpha 通道的图像；opaque 强制使用实色背景。不传则由模型决定。
            seed:
              type: integer
              minimum: 0
              maximum: 2147483647
              description: 可选的随机种子，0-2147483647。不传则自动选取。
    SubmitResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        data:
          type: object
          required:
            - task_id
            - status
            - created_time
          properties:
            task_id:
              type: string
              example: task-unified-1757165031-uyujaw3d
            status:
              type: string
              enum:
                - not_started
                - running
                - finished
                - failed
              example: not_started
              description: >-
                任务状态。提交后立即返回时始终为
                `not_started`。后续状态请通过[查询任务状态](/zh/api-manual/task-management/status)接口或
                `callback_url` 获取。


                - `not_started`：排队中，等待处理

                - `running`：生成中

                - `finished`：已完成，结果在 `files` 或 `output` 中

                - `failed`：失败，详情见 `error_message`
            created_time:
              type: string
              format: date-time
              example: '2026-10-13T10:30:00+08:00'
    ErrorResponse:
      type: object
      required:
        - code
        - error
      properties:
        code:
          type: integer
          example: 400
          enum:
            - 200
            - 400
            - 401
            - 402
            - 403
            - 404
            - 408
            - 429
            - 500
            - 502
            - 503
          description: >-
            业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的
            `code` 为 `400`。


            - `200`：成功

            - `400`：请求参数无效

            - `401`：API Key 缺失或无效

            - `402`：积分不足

            - `403`：没有权限

            - `404`：资源不存在

            - `408`：请求超时

            - `429`：请求频率超限

            - `500`：服务器内部错误

            - `502`：上游服务错误

            - `503`：服务暂不可用


            详见[错误码](/zh/api-manual/error-codes)。
        error:
          type: object
          required:
            - message
            - type
          properties:
            message:
              type: string
              example: Invalid request parameters
            type:
              type: string
              example: invalid_request_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        所有 API 接口都需要 Bearer Token 认证。


        创建 API Key：登录 PoYo，进入 **仪表盘 → API
        密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建
        Key。


        在请求头中添加：


        ```

        Authorization: Bearer YOUR_API_KEY

        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.