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

# Submit an asynchronous image task

> Submit idempotent Nano Banana or GPT Image generation and multi-image editing, then poll the provider-native result.

Use this endpoint for asynchronous image integrations. Set `action=generate` without `input_images`, or use `action=edit` with 1–16 Base64 source images. Add `Idempotency-Key` before any submit that may be retried.

Nano Banana uses its model-specific K-size and `aspect_ratio` values. GPT Image uses explicit pixel dimensions and forwards `quality`; the selected upstream determines its effect. Both reverse-image routes use `n=1`.

HTTP `202` means the task was accepted. Persist `task_id`, then poll [Get task](/en/api-reference/get-task) every 2–5 seconds until `completed`, `failed`, or `expired`. Completed results remain available for 24 hours and preserve the selected model family's native response shape.

<Warning>
  Try it creates a real billable task. The form can display an entered key in generated cURL, so use a development key and do not share the command or a credential-bearing screenshot.
</Warning>

<CardGroup cols={2}>
  <Card title="Understand task fields" icon="clock-3" href="/en/unified-api/async-tasks">
    Choose action, model-specific controls, source-image input, and terminal handling.
  </Card>

  <Card title="Implement safe polling" icon="refresh-cw" href="/en/unified-api/polling">
    Enforce a deadline, bounded retry, and model-specific result parsing.
  </Card>
</CardGroup>


## OpenAPI

````yaml openapi.json POST /v1/images/tasks
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/tasks:
    post:
      tags:
        - Asynchronous tasks
      summary: Submit an asynchronous image generation or edit task (billable)
      description: >-
        Recommended task endpoint for Nano Banana and GPT Image. Send
        action=generate without input_images, or action=edit with 1 to 16 Base64
        source images. Use an Idempotency-Key when a submission may be retried.
        A successful request returns HTTP 202 with task_id; poll GET
        /v1/tasks/{task_id}. This is a YingTu extension, not an official Google
        or OpenAI endpoint.
      operationId: submitUnifiedImageTask
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageTaskRequest'
            examples:
              gptImageGenerate:
                summary: Queue a GPT Image generation
                value:
                  model: gpt-image-2-vip
                  action: generate
                  prompt: A silver watch on dark stone, no text
                  size: 2048x2048
                  quality: high
                  'n': 1
              gptImageEdit:
                summary: Queue a GPT Image edit
                value:
                  model: gpt-image-2-vip
                  action: edit
                  prompt: Keep the product and replace the background with pale blue
                  input_images:
                    - mime_type: image/png
                      data: BASE64_SOURCE_IMAGE_1
                    - mime_type: image/jpeg
                      data: BASE64_SOURCE_IMAGE_2
                  size: 2048x2048
                  quality: high
                  'n': 1
              nanoBananaGenerate:
                summary: Queue a Nano Banana generation
                value:
                  model: gemini-3.1-flash-image
                  action: generate
                  prompt: A quiet reading room at sunrise, editorial photography
                  size: 2K
                  aspect_ratio: '16:9'
                  'n': 1
      responses:
        '202':
          description: Task accepted
          headers:
            Idempotent-Replayed:
              description: True when the idempotency key replayed an existing task.
              schema:
                type: boolean
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskAccepted'
              example:
                task_id: task_example
                status: queued
                created_at: 1788307200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '413':
          $ref: '#/components/responses/RequestTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - BearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Recommended unique retry key, up to 255 bytes. Reusing the same key with
        the same normalized request returns the original task; changing the
        request returns HTTP 409.
      schema:
        type: string
        maxLength: 255
      example: image-job-001
  schemas:
    ImageTaskRequest:
      title: Asynchronous image task
      description: >-
        Choose generation or editing with 1 to 16 source images. Model-specific
        size, aspect_ratio, and quality rules still apply.
      oneOf:
        - $ref: '#/components/schemas/ImageTaskGenerateRequest'
        - $ref: '#/components/schemas/ImageTaskEditRequest'
      discriminator:
        propertyName: action
        mapping:
          generate:
            $ref: '#/components/schemas/ImageTaskGenerateRequest'
          edit:
            $ref: '#/components/schemas/ImageTaskEditRequest'
    TaskAccepted:
      type: object
      required:
        - task_id
        - status
        - created_at
      properties:
        task_id:
          type: string
          example: task_01JY8K6M6B4YQ3R8H4T6V2Z1AB
        status:
          type: string
          const: queued
        created_at:
          type: integer
          format: int64
          description: Unix timestamp in seconds.
          example: 1788307200
    ImageTaskGenerateRequest:
      title: Generate image task
      type: object
      required:
        - model
        - action
        - prompt
      properties:
        model:
          $ref: '#/components/schemas/ModelId'
        action:
          type: string
          const: generate
        prompt:
          $ref: '#/components/schemas/ImageTaskPrompt'
        size:
          $ref: '#/components/schemas/ImageTaskSize'
        aspect_ratio:
          $ref: '#/components/schemas/ImageTaskAspectRatio'
        quality:
          $ref: '#/components/schemas/OpenAIImageQuality'
        'n':
          $ref: '#/components/schemas/ImageTaskCount'
    ImageTaskEditRequest:
      title: Edit image task
      type: object
      required:
        - model
        - action
        - prompt
        - input_images
      properties:
        model:
          $ref: '#/components/schemas/ModelId'
        action:
          type: string
          const: edit
        prompt:
          $ref: '#/components/schemas/ImageTaskPrompt'
        input_images:
          title: Source images
          type: array
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/ImageTaskInputImage'
          description: >-
            Provide 1 to 16 source images for edit and omit the field for
            generate. Each decoded file is limited to 20 MiB; all inputs
            together are limited to 64 MiB.
        size:
          $ref: '#/components/schemas/ImageTaskSize'
        aspect_ratio:
          $ref: '#/components/schemas/ImageTaskAspectRatio'
        quality:
          $ref: '#/components/schemas/OpenAIImageQuality'
        'n':
          $ref: '#/components/schemas/ImageTaskCount'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ModelId:
      type: string
      enum:
        - gemini-2.5-flash-image
        - gemini-3.1-flash-lite-image
        - gemini-3.1-flash-image
        - gemini-3-pro-image
        - gpt-image-2-web
        - gpt-image-2-vip
    ImageTaskPrompt:
      title: Prompt
      type: string
      minLength: 1
      example: A quiet reading room at sunrise, editorial photography
    ImageTaskSize:
      title: Output size
      type: string
      enum:
        - 1K
        - 2K
        - 4K
        - 1024x1024
        - 2048x2048
        - 3840x2160
      description: >-
        Use model-specific values: Nano Banana uses its supported K tier or
        omits size where required; GPT Image uses an explicit pixel preset.
    ImageTaskAspectRatio:
      title: Aspect ratio
      type: string
      enum:
        - '1:1'
        - '1:4'
        - '1:8'
        - '2:3'
        - '3:2'
        - '3:4'
        - '4:1'
        - '4:3'
        - '4:5'
        - '5:4'
        - '8:1'
        - '9:16'
        - '16:9'
        - '21:9'
      description: >-
        Nano Banana only. GPT Image must omit aspect_ratio and use an explicit
        pixel size.
    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.
    ImageTaskCount:
      title: Number of images
      type: integer
      enum:
        - 1
      default: 1
      description: Omit n or use 1.
    ImageTaskInputImage:
      title: Base64 source image
      type: object
      required:
        - mime_type
        - data
      properties:
        mime_type:
          title: Source MIME type
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/webp
          description: Must match the decoded file bytes.
        data:
          title: Source Base64
          type: string
          format: byte
          description: >-
            Raw Base64 without a data URL prefix. Decoded data must not exceed
            20 MiB.
    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
    IdempotencyConflict:
      description: The Idempotency-Key already belongs to a different normalized request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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.

````