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

# 提交统一异步图片任务

> 通过统一 JSON 接口提交带幂等保护的 Nano Banana 或 GPT Image 生图与多图编辑任务，并查询各自原生结果。

异步图片接入使用该接口。`action=generate` 时不要传 `input_images`；`action=edit` 时提供 1～16 张 Base64 来源图。可能重试的提交应设置 `Idempotency-Key`。

Nano Banana 使用对应模型允许的 K 档位和 `aspect_ratio`。GPT Image 使用明确像素尺寸并转发 `quality`，实际效果取决于所选上游。两个逆向接口都固定 `n=1`。

HTTP `202` 只表示任务已受理。先保存 `task_id`，再每隔 2～5 秒查询[任务状态](/cn/api-reference/get-task)，直到 `completed`、`failed` 或 `expired`。成功结果保留 24 小时，并保持对应模型家族的原生响应结构。

<Warning>
  在线测试会创建真实计费任务。表单生成的 cURL 可能直接显示已输入的密钥，请使用开发密钥，不要分享命令或带凭证的截图。
</Warning>

<CardGroup cols={2}>
  <Card title="了解任务字段" icon="clock-3" href="/cn/unified-api/async-tasks">
    正确填写 action、模型参数、来源图和终态处理。
  </Card>

  <Card title="实现安全轮询" icon="refresh-cw" href="/cn/unified-api/polling">
    设置截止时间、有限重试，并按模型家族解析结果。
  </Card>
</CardGroup>


## OpenAPI

````yaml openapi-locales/zh-CN/openapi.json POST /v1/images/tasks
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/tasks:
    post:
      tags:
        - Asynchronous tasks
      summary: 提交异步图片生成或编辑任务（真实计费）
      description: >-
        Nano Banana 与 GPT Image 的推荐异步接口。action=generate 时省略
        input_images；action=edit 时提供 1 至 16 张 Base64 来源图。可能重试提交时请使用
        Idempotency-Key。成功后以 HTTP 202 返回 task_id，再轮询 GET /v1/tasks/{task_id}。这是
        YingTu 扩展，不是 Google 或 OpenAI 官方接口。
      operationId: submitUnifiedImageTask
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImageTaskRequest'
            examples:
              gptImageGenerate:
                summary: 提交 GPT Image 异步生图任务
                value:
                  model: gpt-image-2-vip
                  action: generate
                  prompt: 深色石材上的银色腕表，不要文字
                  size: 2048x2048
                  quality: high
                  'n': 1
              gptImageEdit:
                summary: 提交 GPT Image 异步编辑任务
                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: 提交 Nano Banana 异步生图任务
                value:
                  model: gemini-3.1-flash-image
                  action: generate
                  prompt: 日出时分安静的阅览室，纪实摄影风格
                  size: 2K
                  aspect_ratio: '16:9'
                  'n': 1
      responses:
        '202':
          description: 任务已受理
          headers:
            Idempotent-Replayed:
              description: 幂等键命中已有任务时为 true。
              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: 建议为可重试提交设置唯一键，最长 255 字节。相同键与相同规范化请求返回原任务；请求内容变化时返回 HTTP 409。
      schema:
        type: string
        maxLength: 255
      example: image-job-001
  schemas:
    ImageTaskRequest:
      title: 异步图片任务
      description: 选择图片生成，或使用 1 至 16 张来源图编辑；仍需遵循具体模型的 size、aspect_ratio 和 quality 规则。
      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 秒级时间戳。
          example: 1788307200
    ImageTaskGenerateRequest:
      title: 图片生成任务
      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: 图片编辑任务
      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: >-
            edit 提供 1 至 16 张来源图，generate 省略该字段。每个解码文件不超过 20 MiB，全部输入合计不超过 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: 提示词
      type: string
      minLength: 1
      example: A quiet reading room at sunrise, editorial photography
    ImageTaskSize:
      title: 输出尺寸
      type: string
      enum:
        - 1K
        - 2K
        - 4K
        - 1024x1024
        - 2048x2048
        - 3840x2160
      description: 按模型填写：Nano Banana 使用该模型支持的 K 档位，要求省略时不要传；GPT Image 使用明确的像素尺寸。
    ImageTaskAspectRatio:
      title: 宽高比
      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 使用。GPT Image 必须省略 aspect_ratio，并传入明确的像素尺寸。
    OpenAIImageQuality:
      title: 图片质量
      type: string
      enum:
        - low
        - medium
        - high
        - auto
      example: low
      description: 两个 GPT Image 接口都会转发该值；实际效果由所选上游决定。
    ImageTaskCount:
      title: 图片数量
      type: integer
      enum:
        - 1
      default: 1
      description: 省略 n 或传入 1。
    ImageTaskInputImage:
      title: Base64 来源图片
      type: object
      required:
        - mime_type
        - data
      properties:
        mime_type:
          title: 来源图 MIME 类型
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/webp
          description: 必须与 Base64 解码后的文件字节一致。
        data:
          title: 来源图 Base64
          type: string
          format: byte
          description: 仅填写不带 data URL 前缀的 Base64；解码后不得超过 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: 模型、字段或参数值无效
      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
    IdempotencyConflict:
      description: 该 Idempotency-Key 已用于另一份不同的规范化请求
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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。

````