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

# /v1/images/edits

> Edits or inpaints images with OpenAI-compatible image editing models.

使用 `multipart/form-data` 基于一张或多张输入图片创建编辑后的图片。

## GPT Image 2

* `image` 和 `prompt` 必填；单图使用 `image`，多图重复传入 `image[]`
* 使用 GPT Image 2 时请显式传入 `model=gpt-image-2`；未传 `model` 时，ApiGo 默认使用 `dall-e-2`
* 目标模型支持的其他 multipart 字段和文件也可直接传入；`image[]` 可以重复，`model`、`prompt`、`n`、`size`、`quality` 和 `stream` 每个最多传一次
* 未传 `n`、`size` 或 `quality` 时，ApiGo 分别使用 `1`、`1024x1024` 和 `medium`
* 常用编辑参数还包括 `background`、`moderation`、`output_format` 和 `output_compression`；其中 `output_compression` 适用于 JPEG/WebP，取值为 0–100
* `gpt-image-2` 始终以高保真方式处理输入图片，请不要传 `input_fidelity`
* 当前不支持 `stream=true`；编辑结果以 JSON 返回，图片数据位于 `data[].b64_json`

## 蒙版（`mask`）

蒙版必须与第一张输入图片使用相同格式和尺寸，并包含 Alpha 通道。透明区域用于指示需要编辑的位置。

GPT Image 会结合蒙版和提示词理解编辑范围，因此结果不一定严格贴合蒙版边缘。上传多张图片时，蒙版只应用于第一张图片。


## OpenAPI

````yaml POST /v1/images/edits
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-vip.apigo.ai
security:
  - bearerAuth: []
paths:
  /v1/images/edits:
    post:
      summary: OpenAI image edits
      description: 使用兼容 OpenAI 的图片编辑模型，对图片进行编辑或修复。
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OpenAIImagesEditsRequest'
      responses:
        '200':
          description: Successful image edit response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIImagesResponse'
              example:
                created: 1589478378
                background: opaque
                output_format: png
                quality: medium
                size: 1024x1024
                data:
                  - b64_json: iVBORw0KGgoAAA...
                usage:
                  input_tokens: 1549
                  input_tokens_details:
                    image_tokens: 1536
                    text_tokens: 13
                  output_tokens: 1372
                  output_tokens_details:
                    image_tokens: 1372
                    text_tokens: 0
                  total_tokens: 2921
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    OpenAIImagesEditsRequest:
      type: object
      required:
        - image
        - prompt
      properties:
        image:
          oneOf:
            - type: string
              format: binary
              description: 单张输入图片。
            - type: array
              maxItems: 16
              items:
                type: string
                format: binary
              description: 多张输入图片，GPT Image 模型支持。
          description: 一张或多张待编辑的输入图片。
        prompt:
          type: string
          description: 描述编辑目标的文本提示词。
          example: 在图片中添加一朵红色的玫瑰花
        mask:
          type: string
          format: binary
          description: 可选蒙版。需与第一张输入图片同格式、同尺寸并包含 Alpha 通道；透明区域表示需要编辑的位置。
        model:
          type: string
          enum:
            - gpt-image-2
            - gpt-image-1
            - dall-e-2
          default: dall-e-2
          description: 图片编辑模型；未传时 ApiGo 使用 dall-e-2。
        background:
          type: string
          enum:
            - transparent
            - opaque
            - auto
          description: GPT Image 模型的输出背景。gpt-image-2 仅支持 opaque 和 auto。
        input_fidelity:
          type: string
          enum:
            - high
            - low
          description: 控制输入图片细节的保留程度。gpt-image-2 始终使用高保真处理，请勿为该模型传入此参数。
        moderation:
          type: string
          enum:
            - auto
            - low
          description: GPT Image 模型的内容审核级别。
        'n':
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          description: 生成的编辑后图片数量。
        output_compression:
          type: integer
          minimum: 0
          maximum: 100
          default: 100
          description: GPT Image 输出 JPEG/WebP 时的压缩率。
        output_format:
          type: string
          enum:
            - png
            - jpeg
            - webp
          description: GPT Image 输出格式。
        quality:
          type: string
          enum:
            - auto
            - high
            - medium
            - low
            - standard
          description: 不同模型支持的值不同。GPT Image 未传时，ApiGo 使用 medium。
        response_format:
          type: string
          enum:
            - url
            - b64_json
          description: 仅适用于 dall-e-2。
        size:
          type: string
          example: 1024x1024
          description: 允许值取决于模型。gpt-image-2 支持 auto 或符合尺寸约束的自定义分辨率；未传时 ApiGo 使用 1024x1024。
        user:
          type: string
          description: 终端用户的唯一标识。
    OpenAIImagesResponse:
      type: object
      required:
        - created
        - data
      properties:
        created:
          type: integer
          format: int64
          description: Unix 时间戳，单位为秒。
        background:
          type: string
          enum:
            - transparent
            - opaque
            - auto
        output_format:
          type: string
          enum:
            - png
            - jpeg
            - webp
        quality:
          type: string
          enum:
            - auto
            - high
            - medium
            - low
            - hd
            - standard
        size:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/OpenAIImageData'
        usage:
          $ref: '#/components/schemas/OpenAIImageUsage'
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    OpenAIImageData:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: 生成图片的临时 URL。
        b64_json:
          type: string
          description: Base64 编码的图片数据。
        revised_prompt:
          type: string
          description: 上游返回的修订后提示词（如有）。
    OpenAIImageUsage:
      type: object
      properties:
        input_tokens:
          type: integer
        input_tokens_details:
          $ref: '#/components/schemas/OpenAIImageTokenDetails'
        output_tokens:
          type: integer
        output_tokens_details:
          $ref: '#/components/schemas/OpenAIImageTokenDetails'
        total_tokens:
          type: integer
    OpenAIImageTokenDetails:
      type: object
      properties:
        image_tokens:
          type: integer
        text_tokens:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````