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

# 使用 GPT Image 编辑图片

> 查看同步 GPT Image Edit 接口，包括一张 multipart 来源图、编辑提示词、三档尺寸、quality 和 Base64 PNG。

使用 multipart 上传一张 PNG、JPEG 或 WebP。两个逆向接口都会转发 `low`、`medium`、`high` 或 `auto`，实际效果取决于上游。

当前 Images 形式的 Edit 是同步接口。需要 1～16 张参考图时，使用 [`/v1/images/tasks`](/cn/api-reference/image-tasks) 并设置 `action=edit`。

<Warning>在线测试会产生真实编辑费用。请使用开发图片和开发密钥，避免分享带凭证的生成命令。</Warning>


## OpenAPI

````yaml openapi-locales/zh-CN/openapi.json POST /v1/images/edits
openapi: 3.1.0
info:
  title: YingTu 图片 API
  version: 1.0.0
  description: 提供 Gemini 原生 Nano Banana 与 OpenAI Images 形状的 GPT Image 生图、编辑和任务接口。
servers:
  - url: https://api.yingtu.ai
    description: YingTu API
security: []
tags:
  - name: Synchronous generation
    description: 在同一个 HTTP 请求中等待完整 Gemini 响应。
  - name: Asynchronous tasks
    description: 提交图片任务，再查询到任务进入终态。
  - name: GPT Image generation
    description: 同步生成 GPT Image 图片，或提交 YingTu 任务式生图请求。
  - name: GPT Image editing
    description: 使用 GPT Image 同步编辑一张来源图片。
paths:
  /v1/images/edits:
    post:
      tags:
        - GPT Image editing
      summary: 使用 GPT Image 编辑一张来源图片（真实计费）
      description: >-
        上传一张 PNG、JPEG 或 WebP 来源图片，并等待一张 Base64 PNG。异步编辑或多张参考图请使用 POST
        /v1/images/tasks，并设置 action=edit。
      operationId: editGptImageSynchronously
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OpenAIImageEditRequest'
            encoding:
              image:
                contentType: image/png, image/jpeg, image/webp
      responses:
        '200':
          description: 完整图片编辑响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIImagesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  schemas:
    OpenAIImageEditRequest:
      title: GPT Image 编辑请求
      type: object
      required:
        - model
        - prompt
        - image
      properties:
        model:
          $ref: '#/components/schemas/OpenAIImageModelId'
        prompt:
          title: 编辑要求
          type: string
          minLength: 1
          example: 保留产品主体，把背景替换为浅蓝色
        image:
          title: 来源图片
          type: string
          format: binary
          description: 一张 PNG、JPEG 或 WebP 来源图片。
        size:
          $ref: '#/components/schemas/OpenAIImageSize'
        quality:
          $ref: '#/components/schemas/OpenAIImageQuality'
        'n':
          title: 图片数量
          type: integer
          enum:
            - 1
          default: 1
    OpenAIImagesResponse:
      title: GPT Image 响应
      type: object
      required:
        - created
        - data
      properties:
        created:
          type: integer
          format: int64
          description: Unix 秒级时间戳。
        data:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/OpenAIImageData'
        size:
          type: string
          description: Output size when returned by the selected GPT Image route.
        quality:
          type: string
          description: Quality value reported by the selected GPT Image route.
        usage:
          $ref: '#/components/schemas/OpenAIImageUsage'
    OpenAIImageModelId:
      title: GPT Image 模型 ID
      type: string
      enum:
        - gpt-image-2-web
        - gpt-image-2-vip
      example: gpt-image-2-web
    OpenAIImageSize:
      title: 输出尺寸
      type: string
      enum:
        - 1024x1024
        - 2048x2048
        - 3840x2160
      example: 1024x1024
      description: 当前公开支持三档尺寸。请明确传入 size 以获得可预测的像素尺寸；4K 横图使用 3840x2160。
    OpenAIImageQuality:
      title: 图片质量
      type: string
      enum:
        - low
        - medium
        - high
        - auto
      example: low
      description: 两个 GPT Image 接口都会转发该值；实际效果由所选上游决定。
    OpenAIImageData:
      type: object
      required:
        - b64_json
      properties:
        b64_json:
          type: string
          format: byte
          description: 不带 data URL 前缀的 Base64 图片字节。
          example: iVBORw0KGgo=
    OpenAIImageUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          minimum: 0
        output_tokens:
          type: integer
          minimum: 0
        total_tokens:
          type: integer
          minimum: 0
        input_tokens_details:
          $ref: '#/components/schemas/OpenAIImageTokenDetails'
        output_tokens_details:
          $ref: '#/components/schemas/OpenAIImageTokenDetails'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    OpenAIImageTokenDetails:
      type: object
      properties:
        text_tokens:
          type: integer
          minimum: 0
        image_tokens:
          type: integer
          minimum: 0
    ErrorObject:
      type: object
      required:
        - message
        - type
      properties:
        message:
          type: string
        type:
          type: string
          example: invalid_request_error
        param:
          type:
            - string
            - 'null'
        code:
          type:
            - string
            - 'null'
          example: insufficient_user_quota
  responses:
    BadRequest:
      description: 模型、字段或参数值无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: YingTu API Key 缺失或无效
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 密钥有效，但当前账号缺少余额或请求权限
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: Insufficient balance for this request
              type: new_api_error
              param: ''
              code: insufficient_user_quota
    RequestTooLarge:
      description: 解压后的请求体超过当前接入限制。请缩小来源图和 JSON 总体积；当前公开接口未承诺固定的单图字节或像素上限。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: Request body exceeds the current limit
              type: new_api_error
              param: ''
              code: read_request_body_failed
    RateLimited:
      description: >-
        当前所选上游返回了速率、配额、消费或模型容量限制。对于文档中的 Nano Banana 接口，该限制来自官方上游，网关不设置固定的平台侧 RPM
        上限。目前没有单独公布 GPT Image 的网关 RPM 或可用率目标。
      headers:
        Retry-After:
          description: 响应提供时，表示重试前应等待的秒数。
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: 请求未能完成
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: YingTu API Key。

````