> ## 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 Edit

> Ideogram 4.6 Edit 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 4.6 Edit API 是 Ideogram 4.6 API 的图像编辑模型。传入一张源图和提示词，即可替换背景、修改招牌上的文字、重新设计产品图风格，或只重绘蒙版标出的区域。参考图可以引导风格或内容，高精度编辑会还原所有未要求修改的像素。如果只想根据提示词生成图像，请使用 [Ideogram 4.6 API](https://docs.poyo.ai/zh/api-manual/image-series/ideogram-v4-6.md) 文生图模型。

## Ideogram 4.6 API 模型

* **ideogram-v4.6-edit** — 编辑恰好一张源图，可选蒙版、参考图和精度控制
* **ideogram-v4.6** — 文生图。参见 [Ideogram V4.6](https://docs.poyo.ai/zh/api-manual/image-series/ideogram-v4-6.md)

## Ideogram 4.6 Edit API 功能

* **提示词编辑**：用自然语言描述要做的修改。需要原样出现在图上的文字，请用引号括起来。
* **蒙版编辑**：蒙版中黑色区域会被编辑，白色区域保持不变。
* **参考图**：最多添加四张参考图，设置蒙版时最多三张。
* **高精度编辑**：`edit_precision: high` 进行精确编辑，并还原未改动的像素。
* **保留完整分辨率的局部编辑**：设置 `context_window: auto` 时，Ideogram 4.6 Edit API 只编辑蒙版周围的区域，并保留源图分辨率。
* **批量、背景与种子**：每次请求最多输出 8 张结果，常规编辑支持透明背景，并可用种子复现结果。

## 编辑模式

| 模式 | 设置 | 效果 |
| - | - | - |
| 常规编辑（默认） | `edit_precision: regular` | 根据提示词重新生成图像。不使用蒙版时，可通过 `size` 改变输出尺寸。支持 `background`。 |
| 高精度编辑 | `edit_precision: high`、`context_window: none` | 对整张图进行精确编辑，并还原未改动的像素。输出保留原始分辨率。 |
| 局部编辑 | `edit_precision: high`、`context_window: auto`、`mask_url` | 只编辑蒙版周围的区域，保留原始分辨率和该区域之外的所有像素。蒙版过大时会退回整图编辑。 |

## 必填参数

* `prompt` (string)：描述修改内容的提示词，1–10,000 个字符，必须包含非空白文本。
* `image_urls` (array of strings)：恰好一张源图。使用公开的 HTTP(S) 图像 URL 或 base64 图像 data URI（`data:image/<type>;base64,...`）。即使只有一张图，也必须传数组。

## 可选参数

* `mask_url` (string)：与源图尺寸相同的蒙版图。黑色区域会被编辑，白色区域保持不变，蒙版必须同时包含两者。可使用公开的 HTTP(S) URL 或 base64 图像 data URI。要求 `size` 为 `auto`。
* `reference_image_urls` (array of strings)：0 到 4 张参考图，设置 `mask_url` 时最多 3 张。可使用公开的 HTTP(S) URL 或 base64 图像 data URI。
* `edit_precision` (string)：`regular` 或 `high`。默认为 `regular`。`regular` 重新生成图像；`high` 进行精确编辑并还原未改动的像素。`high` 要求 `size` 为 `auto`。
* `context_window` (string)：`none` 或 `auto`。默认为 `none`。`auto` 要求 `edit_precision: high` 并提供 `mask_url`。参见[编辑模式](#编辑模式)。
* `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 像素的输出。
* `background` (string)：`transparent` 或 `opaque`。仅限常规编辑；`edit_precision` 为 `high` 时会被拒绝。
* `n` (integer)：结果数量，`1` 到 `8`。默认为 `1`。
* `seed` (integer)：随机种子，`0` 到 `2147483647`。不传则自动选取。
* `callback_url` (string)：可选的 Webhook URL，用于任务完成通知。放在请求顶层，不要放进 `input`。

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

## 尺寸

* `auto`（默认）保留源图的几何尺寸。在 Ideogram 4.6 Edit API 中，使用 `mask_url` 或 `edit_precision: high` 时只能用 `auto`，否则请求会失败，错误信息为 "mask\_url or high edit\_precision requires size auto"。
* 不使用蒙版的常规编辑还可以使用预设 `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`。宽和高都必须在 `256` 到 `4096` 像素之间且为 `32` 的倍数，宽高比须在 `1:6` 到 `6:1` 之间。

## 输出

Ideogram 4.6 Edit API 任务状态为 `finished` 时，`files` 中每张编辑后的图像对应一项，包含 `file_url` 和 `file_type: image`。

## Ideogram 4.6 Edit API 示例

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

### 编辑图像

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

### 局部蒙版编辑

```json theme={"dark"}
{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Change the sign text to \"OPEN LATE\"",
    "image_urls": [
      "https://example.com/storefront.png"
    ],
    "mask_url": "https://example.com/sign-mask.png",
    "edit_precision": "high",
    "context_window": "auto",
    "quality": "high"
  }
}
```

只编辑蒙版黑色部分周围的区域，并保留原始分辨率。

### 参考图风格迁移

```json theme={"dark"}
{
  "model": "ideogram-v4.6-edit",
  "input": {
    "prompt": "Restyle the product shot to match the reference",
    "image_urls": [
      "https://example.com/product.png"
    ],
    "reference_image_urls": [
      "https://example.com/style.png"
    ],
    "size": "2048x2048",
    "quality": "low",
    "n": 2
  }
}
```

## 注意事项

* Ideogram 4.6 Edit API 要求 `image_urls` 中恰好包含一张源图。
* `context_window: auto` 未同时设置 `edit_precision: high` 和 `mask_url` 时会被拒绝。
* `very_low` 与超过 4,194,304 像素的自定义尺寸同时使用时会被拒绝。
* 源图、蒙版和参考图可以是公开的 HTTP(S) URL 或 base64 图像 data URI。如需使用本地文件，也可以先通过[文件管理](https://docs.poyo.ai/zh/api-manual/file-series/upload-url.md)上传。
* 生成的图像文件在创建后 3 天内可访问，请及时下载保存。
* 响应返回 `task_id`，请通过查询任务状态获取编辑后的图像。


## OpenAPI

````yaml zh/api-manual/image-series/ideogram-v4-6-edit.json POST /api/generate/submit
openapi: 3.1.0
info:
  title: PoYo AI - Ideogram V4.6 Edit API
  description: Ideogram 4.6 Edit API 根据文本提示词编辑一张源图，支持可选蒙版、最多四张参考图、常规或高精度编辑，以及保留原始分辨率的局部编辑。
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Ideogram V4.6 Edit
      summary: 提交 Ideogram V4.6 Edit 任务
      description: Ideogram 4.6 Edit API 图像编辑，支持可选蒙版、参考图，以及常规、高精度或局部编辑。
      operationId: submit_ideogram_v4_6_edit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitRequest'
            examples:
              image-edit:
                summary: 编辑图像
                value:
                  model: ideogram-v4.6-edit
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: Replace the background with a blue photo studio
                    image_urls:
                      - https://example.com/source.png
              localized-masked-edit:
                summary: 局部蒙版编辑
                value:
                  model: ideogram-v4.6-edit
                  input:
                    prompt: Change the sign text to "OPEN LATE"
                    image_urls:
                      - https://example.com/storefront.png
                    mask_url: https://example.com/sign-mask.png
                    edit_precision: high
                    context_window: auto
                    quality: high
              reference-restyle:
                summary: 参考图风格迁移
                value:
                  model: ideogram-v4.6-edit
                  input:
                    prompt: Restyle the product shot to match the reference
                    image_urls:
                      - https://example.com/product.png
                    reference_image_urls:
                      - https://example.com/style.png
                    size: 2048x2048
                    quality: low
                    'n': 2
      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-edit
          description: Ideogram 4.6 Edit 模型标识。
        callback_url:
          type: string
          format: uri
          description: 可选的 Webhook URL，任务完成或失败时通知。
        input:
          type: object
          additionalProperties: false
          required:
            - prompt
            - image_urls
          description: 编辑恰好一张源图。
          properties:
            prompt:
              type: string
              minLength: 1
              maxLength: 10000
              pattern: \S
              description: 必填。描述修改内容的提示词，1-10,000 个字符，必须包含非空白文本。
            image_urls:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
                pattern: ^(https?://\S+|data:image/[A-Za-z0-9.+-]+;base64,\S+)$
                description: 公开的 HTTP(S) 图像 URL 或 base64 图像 data URI。
              description: 必填。恰好一张待编辑的源图，使用公开的 HTTP(S) 图像 URL 或 base64 图像 data URI。必须为数组。
            mask_url:
              type: string
              pattern: ^(https?://\S+|data:image/[A-Za-z0-9.+-]+;base64,\S+)$
              description: >-
                可选。与源图尺寸相同的蒙版。黑色区域会被编辑，白色区域保持不变，必须同时包含两者。可使用公开的 HTTP(S) URL 或
                base64 图像 data URI。要求 size 为 auto。
            reference_image_urls:
              type: array
              minItems: 0
              maxItems: 4
              items:
                type: string
                pattern: ^(https?://\S+|data:image/[A-Za-z0-9.+-]+;base64,\S+)$
                description: 公开的 HTTP(S) 图像 URL 或 base64 图像 data URI。
              description: >-
                可选参考图：0-4 张，设置 mask_url 时最多 3 张。可使用公开的 HTTP(S) URL 或 base64 图像
                data URI。
            edit_precision:
              type: string
              enum:
                - regular
                - high
              default: regular
              description: regular（默认）重新生成图像；high 进行精确编辑并还原未改动的像素，要求 size 为 auto。
            context_window:
              type: string
              enum:
                - none
                - auto
              default: none
              description: >-
                none（默认）或 auto。在 edit_precision 为 high 时，none
                编辑整张图，并保留原始分辨率。auto 要求提供 mask_url 且 edit_precision 为
                high，只编辑蒙版周围的区域，并保留原始分辨率。
            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（默认）保留源图的几何尺寸。1:1、1:1 HD、4:3、3:4、16:9、9:16 或自定义
                WIDTHxHEIGHT（每边 256-4096 像素、32 的倍数、宽高比在 1:6 到 6:1 之间）只适用于不使用
                mask_url 的常规编辑。超过 4,194,304 像素的输出不支持 very_low。
            quality:
              type: string
              enum:
                - very_low
                - low
                - medium
                - high
              default: medium
              description: 输出质量，默认为 medium。very_low 只适用于不超过 4,194,304 像素（面积 2048x2048）的输出。
            background:
              type: string
              enum:
                - transparent
                - opaque
              description: >-
                可选，仅限常规编辑（edit_precision 为 high 时会被拒绝）。transparent 返回带 alpha
                通道的图像；opaque 强制使用实色背景。
            'n':
              type: integer
              minimum: 1
              maximum: 8
              default: 1
              description: 输出图像数量，1-8，默认为 1。必须为整数。
            seed:
              type: integer
              minimum: 0
              maximum: 2147483647
              description: 可选的随机种子，0-2147483647。不传则自动选取。
          allOf:
            - if:
                required:
                  - mask_url
              then:
                properties:
                  reference_image_urls:
                    maxItems: 3
                  size:
                    const: auto
            - if:
                required:
                  - edit_precision
                properties:
                  edit_precision:
                    const: high
              then:
                properties:
                  size:
                    const: auto
                not:
                  required:
                    - background
            - if:
                required:
                  - context_window
                properties:
                  context_window:
                    const: auto
              then:
                required:
                  - mask_url
                  - edit_precision
                properties:
                  edit_precision:
                    const: high
    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.