> ## 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.5

> Ideogram 4.5 API 根据提示词生成图像，或编辑一张主图。编辑时最多可添加四张参考图，设置蒙版时最多三张；高精度模式会保留未编辑区域的像素。

> [!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-v4.5** - 文生图，支持质量和尺寸控制
* **ideogram-v4.5-edit** - 编辑恰好一张主图，可选参考图、蒙版和精度控制

## 必填参数

* **model**：`ideogram-v4.5` 或 `ideogram-v4.5-edit`
* **input.prompt**：两个模型均必填。使用 `1-10000` 个字符，且须包含非空白文本
* **input.image\_urls**：`ideogram-v4.5-edit` 必填。恰好一张主图。`ideogram-v4.5` 不支持

## 可选参数

* **n**：输出图像数量。取值为 `1` 到 `8` 的整数。默认为 `1`
* **quality**：输出质量。默认为 `medium`。`ideogram-v4.5` 接受 `low`、`medium` 和 `high`。`ideogram-v4.5-edit` 还接受 `very_low`
* **size**：输出尺寸。参见下方的尺寸规则
* **reference\_image\_urls**：仅限编辑。不使用蒙版时最多四张参考图，设置 `mask_url` 时最多三张
* **mask\_url**：仅限编辑。必须与主图尺寸一致，且同时包含黑色编辑区域和白色保留区域。图像内容要求在处理过程中检查。需要 `size=auto` 或省略 `size`
* **edit\_precision**：仅限编辑。`regular` 或 `high`。默认为 `regular`。`high` 会还原未改动的像素，需要 `size=auto` 或省略 `size`
* **callback\_url**：可选的 Webhook URL，用于任务完成通知

所有图像字段都接受公开的 HTTP(S) 图像 URL 或图像 data URI。

## 尺寸

`ideogram-v4.5` 默认为 `1:1 HD`。它接受宽高比 `1:1`、`1:1 HD`、`4:3`、`3:4`、`16:9` 和 `9:16`，或以下任一精确尺寸：

`1024x1024`, `1024x3072`, `1120x896`, `1152x2944`, `1152x864`, `1248x3328`, `1248x832`, `1280x3072`, `1280x720`, `1280x800`, `1296x3168`, `1440x2560`, `1440x2880`, `1440x720`, `1600x2560`, `1664x2496`, `1728x2304`, `1792x2240`, `2048x2048`, `2240x1792`, `2304x1728`, `2496x1664`, `2560x1440`, `2560x1600`, `2880x1440`, `2944x1152`, `3072x1024`, `3072x1280`, `3168x1296`, `3328x1248`, `720x1280`, `720x1440`, `800x1280`, `832x1248`, `864x1152`, `896x1120`.

`ideogram-v4.5-edit` 默认为 `auto`，保留源图尺寸。

* 使用蒙版或 `edit_precision=high` 时，需要 `auto` 或省略尺寸。
* 比例预设和自定义 `WIDTHxHEIGHT` 尺寸仅适用于无蒙版的常规编辑。
* 自定义编辑尺寸的每个维度至少为 `256` 且能被 `32` 整除，总像素数不超过 `4,194,304`，宽高比不超过 `6:1`。

## 示例

### 生成图像

```json theme={"dark"}
{
  "model": "ideogram-v4.5",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A ceramic robot with a clean silhouette."
  }
}
```

### 编辑图像

```json theme={"dark"}
{
  "model": "ideogram-v4.5-edit",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "Replace the background with a blue studio.",
    "image_urls": [
      "https://example.com/source.png"
    ]
  }
}
```

### 高精度蒙版编辑

```json theme={"dark"}
{
  "model": "ideogram-v4.5-edit",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "Replace the black mask area with flowers.",
    "image_urls": [
      "https://example.com/source.png"
    ],
    "mask_url": "https://example.com/mask.png",
    "reference_image_urls": [
      "https://example.com/flowers.png"
    ],
    "edit_precision": "high"
  }
}
```

## 注意事项

* `ideogram-v4.5-edit` 要求 `image_urls` 中恰好有一张主图。
* 通过标准的任务状态 API 查询状态。
* 成功响应返回 `files`，其中生成的图像为 `file_type: image`。


## OpenAPI

````yaml zh/api-manual/image-series/ideogram-v4-5.json POST /api/generate/submit
openapi: 3.1.0
info:
  title: PoYo AI - Ideogram V4.5 API
  description: >-
    Ideogram 4.5 API
    可根据提示词生成图像，或编辑一张主图。编辑时最多可添加四张参考图，设置蒙版时最多三张；高精度模式会保留未编辑区域的像素。
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Ideogram V4.5
      summary: 提交 Ideogram V4.5 任务
      description: 根据提示词生成图像，或结合参考图、可选蒙版和精度控制编辑一张主图。
      operationId: submit_ideogram_v4_5
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              text-to-image:
                summary: 文生图
                value:
                  model: ideogram-v4.5
                  input:
                    prompt: A ceramic robot with a clean silhouette.
              image-edit:
                summary: 编辑一张主图
                value:
                  model: ideogram-v4.5-edit
                  input:
                    prompt: Replace the background with a blue studio.
                    image_urls:
                      - https://example.com/source.png
              masked-edit:
                summary: 使用蒙版和参考图的高精度编辑
                value:
                  model: ideogram-v4.5-edit
                  input:
                    prompt: Replace the black mask area with flowers.
                    image_urls:
                      - https://example.com/source.png
                    mask_url: https://example.com/mask.png
                    reference_image_urls:
                      - https://example.com/flowers.png
                    edit_precision: high
      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
      properties:
        model:
          type: string
          enum:
            - ideogram-v4.5
            - ideogram-v4.5-edit
          description: 文生图使用 ideogram-v4.5，图像编辑使用 ideogram-v4.5-edit。
        input:
          $ref: '#/components/schemas/ModelInput'
        callback_url:
          type: string
          format: uri
          description: 可选的完成或失败回调 URL。
      allOf:
        - if:
            required:
              - model
            properties:
              model:
                const: ideogram-v4.5
          then:
            properties:
              input:
                $ref: '#/components/schemas/GenerationInput'
        - if:
            required:
              - model
            properties:
              model:
                const: ideogram-v4.5-edit
          then:
            properties:
              input:
                $ref: '#/components/schemas/EditInput'
    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
    ModelInput:
      additionalProperties: false
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          maxLength: 10000
          minLength: 1
          description: >-
            ideogram-v4.5 和 ideogram-v4.5-edit 均必填。生成或编辑提示词，1–10,000
            个字符，且须包含非空白内容。
        image_urls:
          type: array
          items:
            type: string
            description: 公开图片 URL 或图片 data URI。
            format: uri
          minItems: 1
          maxItems: 1
          description: >-
            仅 ideogram-v4.5-edit 必填；ideogram-v4.5 不支持。必须恰好一张主源图，以公开 HTTP(S) 图片
            URL 或图片 data URI 提供。
        reference_image_urls:
          maxItems: 4
          type: array
          items:
            type: string
            description: 公开图片 URL 或图片 data URI。
            format: uri
          description: >-
            可选，仅限 ideogram-v4.5-edit。未提供 mask_url 时最多四张参考图，提供 mask_url
            时最多三张。请提供公开 HTTP(S) 图片 URL 或图片 data URI。
        mask_url:
          type: string
          description: >-
            可选，仅限 ideogram-v4.5-edit。公开 HTTP(S) 图片 URL 或图片 data
            URI。尺寸必须与主图一致，且同时包含黑色（编辑）和白色（保留）区域；图像内容要求在处理时检查。要求 size=auto 或不传
            size。
          format: uri
        'n':
          minimum: 1
          default: 1
          maximum: 8
          type: integer
          description: 两个模型的输出图像数量。1 到 8 的整数；默认 1。
        quality:
          enum:
            - very_low
            - low
            - medium
            - high
          default: medium
          type: string
          description: >-
            输出质量；两个模型默认均为 medium。ideogram-v4.5 接受 low、medium 和
            high。ideogram-v4.5-edit 还接受 very_low。
        size:
          type: string
          description: >-
            ideogram-v4.5 默认 1:1 HD，接受 1:1、1:1
            HD、4:3、3:4、16:9、9:16，或以下精确尺寸：1024x1024, 1024x3072, 1120x896,
            1152x2944, 1152x864, 1248x3328, 1248x832, 1280x3072, 1280x720,
            1280x800, 1296x3168, 1440x2560, 1440x2880, 1440x720, 1600x2560,
            1664x2496, 1728x2304, 1792x2240, 2048x2048, 2240x1792, 2304x1728,
            2496x1664, 2560x1440, 2560x1600, 2880x1440, 2944x1152, 3072x1024,
            3072x1280, 3168x1296, 3328x1248, 720x1280, 720x1440, 800x1280,
            832x1248, 864x1152, 896x1120。ideogram-v4.5-edit 默认
            auto，即保留源图尺寸。使用蒙版或 edit_precision=high 时，要求 size 为 auto
            或不传。显式比例预设或自定义 WIDTHxHEIGHT 尺寸仅适用于无蒙版的 regular 编辑。自定义编辑尺寸的宽和高均须至少
            256 且能被 32 整除，总像素不超过 4,194,304，宽高比不超过 6:1。
        edit_precision:
          enum:
            - regular
            - high
          type: string
          description: >-
            可选，仅限 ideogram-v4.5-edit。图像编辑默认 regular。high 启用高精度编辑并还原未改动的像素，要求
            size=auto 或不传 size。
  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.