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

# Ideogram 4.5 图像编辑

> Ideogram 4.5 图像编辑 API 根据文字指令编辑一张图片，支持可选蒙版、最多 4 张参考图，以及 regular 或 high 两档编辑精度。

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

Ideogram 4.5 图像编辑根据文字指令修改一张已有图片。可以用蒙版把编辑限定在某个区域，用最多四张参考图引导结果；需要其余部分保持像素级不变时，选择 `high` 编辑精度。常见用途包括替换商品或招牌文字、修饰背景、批量制作设计变体。Ideogram 称该模型可以避免多次连续编辑后累积的偏色和瑕疵。

Ideogram 4.5 是 Ideogram 面向文字密集型画面和精确编辑的图像模型。Vidgo 提供两个 model ID：[文生图](https://docs.vidgo.ai/zh/api-manual/image-series/ideogram-v4-5-text-to-image.md)和[图像编辑](https://docs.vidgo.ai/zh/api-manual/image-series/ideogram-v4-5-edit.md)。

## 模型

* **ideogram/v4.5/edit** — Ideogram 4.5 图像编辑：一张原图，可选蒙版和参考图。

## 功能

* 用自然语言指令进行图像编辑，包括替换画面中的文字。
* 可选蒙版，把编辑限定在某个区域。
* 最多 4 张风格或内容参考图（使用蒙版时最多 3 张）。
* `edit_precision: high` 适合其余部分必须保持不变的编辑。
* 四档质量（含用于低成本草稿的 `very_low`），每次请求 1–8 张结果。

## 输入模式

* **指令编辑**：`image_urls` + `prompt`，由模型决定修改哪个区域。
* **蒙版编辑**：再加 `mask_url`（黑色为编辑区域，白色为保留区域），并保持 `size: auto`。
* 两种模式都可以加 `reference_image_urls`。

## 必填参数

* `prompt`（string）：要改什么、怎么改，1–10,000 个字符。不能为空白。
* `image_urls`（string\[]）：恰好一张要编辑的图片。公开 HTTP(S) URL 或 `data:image/...;base64,...` 格式的 data URI。

## 可选参数

* `mask_url`（string）：与原图尺寸一致的蒙版，须同时包含黑色（编辑）和白色（保留）。要求 `size: auto`。
* `reference_image_urls`（string\[]）：最多 4 张参考图；使用 `mask_url` 时最多 3 张。参考图只引导结果，本身不会被编辑。
* `edit_precision`（string）：`regular` 或 `high`。默认 `regular`。`high` 要求 `size: auto`。
* `quality`（string）：`very_low`、`low`、`medium` 或 `high`。默认 `medium`。
* `n`（integer）：结果张数，`1`–`8`。默认 `1`。
* `size`（string）：输出尺寸。默认 `auto`。见[尺寸](#尺寸)。

## 尺寸

* `auto`（默认）保持原图尺寸。发送 `mask_url` 或 `edit_precision: high` 时必须使用 `auto`。
* 预设：`1:1`、`1:1 HD`、`4:3`、`3:4`、`16:9`、`9:16`。
* 自定义 `WIDTHxHEIGHT`，例如 `1536x1024`：每边至少 256 且为 32 的倍数，总像素不超过 4,194,304（2048x2048），宽高比不超过 6:1。

## 输出

任务完成后，[查询任务状态](https://docs.vidgo.ai/zh/api-manual/task-management/status.md)和回调内容的 `files` 数组中会按请求的张数（`n`）返回对应数量的图片文件。

## 示例

* **仅文字指令编辑**：修改店铺招牌上的文字，`size: auto`，`medium` 质量。
* **蒙版编辑，带参考图和高精度**：沙发区域蒙版加一张扶手椅参考图，`edit_precision: high`，`quality: high`，并提供 `callback_url`。

## 注意事项

* `image_urls` 必须恰好包含一张图片。要从零生成图片，请用 [Ideogram 4.5 文生图](https://docs.vidgo.ai/zh/api-manual/image-series/ideogram-v4-5-text-to-image.md)。
* 使用 `mask_url` 或 `edit_precision: high` 时 `size` 不是 `auto` 会返回 400；蒙版同时搭配 4 张参考图也会返回 400。
* 上文未列出的字段会返回 400。`model` 和 `callback_url` 放在请求根级，不要放进 `input`。
* 积分在提交时预扣，只取决于 `quality` 和 `n`；`size`、蒙版和参考图不影响价格。任务失败会全额退还。当前费率见[定价页](https://vidgo.ai/apis/api-pricing)。


## OpenAPI

````yaml zh/api-manual/image-series/ideogram-v4-5-edit.json POST /api/generate/submit
openapi: 3.0.0
info:
  title: Vidgo API - Ideogram 4.5 图像编辑
  description: >-
    Ideogram 4.5 图像编辑 API 根据文字指令编辑一张图片，支持可选蒙版、最多 4 张参考图，以及 regular 或 high
    两档编辑精度。
  version: 1.0.0
servers:
  - url: https://api.vidgo.ai
    description: 生产环境
security:
  - BearerAuth: []
paths:
  /api/generate/submit:
    post:
      tags:
        - Image Series
      summary: Ideogram 4.5 图像编辑
      description: >-
        只传本模型列出的 `input` 字段，其他字段会返回 400。`mask_url` 和 `edit_precision: high` 都要求
        `size: auto`。图片字段接受公开 HTTP(S) URL 或 `data:image/...;base64,...` 格式的 data
        URI。
      operationId: submit_ideogram_v4_5_edit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              properties:
                model:
                  type: string
                  description: 模型 ID，填 `ideogram/v4.5/edit`。
                  example: ideogram/v4.5/edit
                callback_url:
                  type: string
                  format: uri
                  nullable: true
                  description: >-
                    可选的公开 HTTP(S) 地址，任务变为 `finished` 或 `failed` 时会收到 POST
                    请求。建议使用 HTTPS。省略、传 `null` 或空字符串即不发送回调。
                  example: https://your-domain.com/callback
                input:
                  type: object
                  required:
                    - prompt
                    - image_urls
                  properties:
                    prompt:
                      type: string
                      minLength: 1
                      maxLength: 10000
                      example: Change the shop sign to read "OPEN LATE" in neon pink
                      description: 编辑指令：要改什么、怎么改。1–10,000 个字符，不能为空白。
                    image_urls:
                      type: array
                      items:
                        type: string
                        format: uri
                      minItems: 1
                      maxItems: 1
                      example:
                        - https://example.com/storefront.png
                      description: 要编辑的图片，恰好一张：公开 HTTP(S) URL 或图片 data URI。
                    mask_url:
                      type: string
                      format: uri
                      description: >-
                        可选的编辑区域蒙版，尺寸与原图一致。黑色为要编辑的区域，白色为保留区域。要求 `size: auto`。公开
                        HTTP(S) URL 或图片 data URI。
                    reference_image_urls:
                      type: array
                      items:
                        type: string
                        format: uri
                      maxItems: 4
                      description: >-
                        可选的风格或内容参考图：最多 4 张；设置 `mask_url` 时最多 3
                        张。参考图只用于引导编辑，本身不会被修改。公开 HTTP(S) URL 或图片 data URI。
                    edit_precision:
                      type: string
                      enum:
                        - regular
                        - high
                      default: regular
                      description: >-
                        `regular` 或 `high`。`high` 会更严格地保持未修改的像素不变，要求 `size:
                        auto`。
                    quality:
                      type: string
                      enum:
                        - very_low
                        - low
                        - medium
                        - high
                      default: medium
                      description: 渲染质量，决定计费档位。`very_low` 仅本编辑 ID 可用。
                    'n':
                      type: integer
                      minimum: 1
                      maximum: 8
                      default: 1
                      description: 生成的图片张数。
                    size:
                      type: string
                      default: auto
                      example: auto
                      description: >-
                        输出尺寸。`auto` 保持原图尺寸。否则可用预设（`1:1`、`1:1
                        HD`、`4:3`、`3:4`、`16:9`、`9:16`），或 `WIDTHxHEIGHT`：每边至少 256
                        且为 32 的倍数，总像素不超过 4,194,304，宽高比不超过 6:1。使用 `mask_url` 或
                        `edit_precision: high` 时必须为 `auto`。
                  additionalProperties: false
                  description: 生成参数。
            examples:
              instruction_edit:
                summary: 仅文字指令编辑
                value:
                  model: ideogram/v4.5/edit
                  input:
                    prompt: Change the shop sign to read "OPEN LATE" in neon pink
                    image_urls:
                      - https://example.com/storefront.png
                    quality: medium
                    'n': 1
                    size: auto
              masked_edit:
                summary: 蒙版编辑，带参考图和高精度
                value:
                  model: ideogram/v4.5/edit
                  callback_url: https://your-domain.com/callback
                  input:
                    prompt: >-
                      Replace the sofa with the green velvet armchair from the
                      reference image
                    image_urls:
                      - https://example.com/living-room.png
                    mask_url: https://example.com/sofa-mask.png
                    reference_image_urls:
                      - https://example.com/armchair.png
                    edit_precision: high
                    quality: high
                    'n': 1
                    size: auto
      responses:
        '200':
          description: 任务已提交
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: integer
                    enum:
                      - 200
                    description: HTTP 状态码。
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - created_time
                    properties:
                      task_id:
                        type: string
                        description: >-
                          任务
                          ID，用于[查询任务状态](/zh/api-manual/task-management/status)。
                      status:
                        type: string
                        enum:
                          - not_started
                        description: 任务的初始状态。
                      created_time:
                        type: string
                        format: date-time
                        description: 任务创建时间（ISO 8601）。
              example:
                code: 200
                data:
                  task_id: task-unified-1762160000-abc123
                  status: not_started
                  created_time: '2026-11-03T10:30:00'
        '400':
          description: 输入无效、字段不受支持、媒体无法访问或积分不足
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '401':
          description: 凭证无效
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '403':
          description: 拒绝访问
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '404':
          description: 模型未知或已停用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '408':
          description: 请求超时
          content:
            text/plain:
              schema:
                type: string
              example: Request timeout
        '422':
          description: JSON 无效或请求体不是对象
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '429':
          description: 超出速率限制或 API Key 积分限额
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '500':
          description: 内部错误
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '502':
          description: 无法创建上游生成任务
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
        '503':
          description: 所请求的模型暂时不可用
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: true
                      - type: array
                        items: {}
                    description: 错误信息。
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        所有 API 接口都需要 Bearer Token 认证


        获取 API Key：


        进入 **仪表盘 → API 密钥**（[API Key
        管理页面](https://vidgo.ai/apis/dashboard/api-key)）获取你的 API Key


        在请求头中添加：


        ```

        Authorization: Bearer VIDGO_API_KEY

        ```

````

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