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

# Edit an image with GPT Image

> Inspect the synchronous GPT Image Edit operation for one multipart source image, an edit prompt, supported sizes, quality, and Base64 PNG output.

Upload one PNG, JPEG, or WebP source image with a prompt. Both reverse-image routes forward `low`, `medium`, `high`, or `auto`; the selected upstream determines the effect.

This Images-shaped operation is synchronous. For asynchronous work with 1–16 reference images, submit JSON to [`/v1/images/tasks`](/en/api-reference/image-tasks) with `action=edit`.

<Warning>
  Try it can create a real billable edit. Use a development image and key, and do not share authenticated generated cURL.
</Warning>


## OpenAPI

````yaml openapi.json POST /v1/images/edits
openapi: 3.1.0
info:
  title: YingTu Image API
  version: 1.0.0
  description: >-
    Gemini-native Nano Banana and OpenAI Images-shaped GPT Image generation,
    editing, and task APIs.
servers:
  - url: https://api.yingtu.ai
    description: YingTu API
security: []
tags:
  - name: Synchronous generation
    description: Wait for a complete Gemini response in one HTTP request.
  - name: Asynchronous tasks
    description: >-
      Submit image work, then retrieve the task until it reaches a terminal
      state.
  - name: GPT Image generation
    description: >-
      Generate GPT Image output synchronously or submit a YingTu task-ID
      generation request.
  - name: GPT Image editing
    description: Edit one source image synchronously with GPT Image.
paths:
  /v1/images/edits:
    post:
      tags:
        - GPT Image editing
      summary: Edit one source image with GPT Image (billable)
      description: >-
        Upload one PNG, JPEG, or WebP source image and wait for one Base64 PNG
        result. For asynchronous editing or multiple reference images, use POST
        /v1/images/tasks with 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: Complete edited image response
          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 edit request
      type: object
      required:
        - model
        - prompt
        - image
      properties:
        model:
          $ref: '#/components/schemas/OpenAIImageModelId'
        prompt:
          title: Edit instruction
          type: string
          minLength: 1
          example: Keep the product and replace the background with pale blue
        image:
          title: Source image
          type: string
          format: binary
          description: One PNG, JPEG, or WebP source image.
        size:
          $ref: '#/components/schemas/OpenAIImageSize'
        quality:
          $ref: '#/components/schemas/OpenAIImageQuality'
        'n':
          title: Number of images
          type: integer
          enum:
            - 1
          default: 1
    OpenAIImagesResponse:
      title: GPT Image response
      type: object
      required:
        - created
        - data
      properties:
        created:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
        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 model ID
      type: string
      enum:
        - gpt-image-2-web
        - gpt-image-2-vip
      example: gpt-image-2-web
    OpenAIImageSize:
      title: Output size
      type: string
      enum:
        - 1024x1024
        - 2048x2048
        - 3840x2160
      example: 1024x1024
      description: >-
        Current public presets. Set size explicitly for predictable dimensions;
        the 4K landscape value is 3840x2160.
    OpenAIImageQuality:
      title: Image quality
      type: string
      enum:
        - low
        - medium
        - high
        - auto
      example: low
      description: >-
        Forwarded for both GPT Image routes. The selected upstream determines
        how the requested value affects the result.
    OpenAIImageData:
      type: object
      required:
        - b64_json
      properties:
        b64_json:
          type: string
          format: byte
          description: Base64-encoded image bytes without a data URL prefix.
          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: Invalid model, field, or parameter value
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid YingTu API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        The key is valid but the account lacks balance or access for this
        request
      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: >-
        The decompressed request body exceeds a current ingress limit. Reduce
        the source image and total JSON body; the public contract does not
        promise one fixed source-image byte or pixel maximum.
      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: >-
        The selected upstream provider returned a rate, quota, spend, or
        model-capacity limit. For the documented Nano Banana routes, this is the
        official upstream provider and the gateway does not apply a fixed
        platform-side RPM cap. No separate GPT Image gateway RPM or availability
        objective is currently published.
      headers:
        Retry-After:
          description: Seconds to wait before retrying when supplied.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: The request could not be completed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: YingTu API key.

````