12API logo12API
API 手册

异步图片任务

提交图片生成或编辑任务，并通过轮询或回调获取结果 URL

异步图片任务适合批量生成、后台处理、长耗时图片任务，以及需要直接获取图片 URL 的场景。提交任务后接口立即返回任务 ID，生成完成后通过查询接口获取结果，也可以通过 callback_url 接收完成通知。

什么时候用异步接口

如果你只生成一张图片，并且能接受同步等待，可以优先使用 NanoBanana 图片 或 GPT Image 2。如果你需要批量、轮询、后台处理或 URL 结果，使用本页接口。

旧路径迁移提醒

旧版 /v1/images/async/generations、/v1/images/async/edits 及对应查询路径仍会保留一段时间，方便现有项目迁移过渡。请正在使用旧路径的用户尽快迁移到 /v1/task/submit 和 /v1/task/{task_id}；后续新模型的兼容与支持都仅在新路径中提供。

接口概览

能力方法路径
提交任务POST/v1/task/submit
查询任务GET/v1/task/{task_id}

所有接口都使用：

Authorization: Bearer $API_KEY

推荐模型

模型适合场景
gemini-3.1-flash-image-preview日常图片生成，质量、速度和成本比较均衡
gemini-3-pro-image-preview专业素材、复杂指令、高分辨率输出
gemini-2.5-flash-image低延迟、大批量、基础图片任务
gpt-image-2GPT Image 2 图片生成与编辑

具体可用模型取决于渠道中配置的模型列表。异步图片任务会将生成结果转存为图片 URL，自部署时需要先配置对象存储。

提交任务

新项目建议使用统一任务格式。它把模型、输入参数和回调地址放在同一个任务结构里，是异步图片任务后续扩展新模型和新能力的主要支持方式。

POST /v1/task/submit
Authorization: Bearer $API_KEY
Content-Type: application/json

请求体

字段类型必填说明
modelstring是图片模型名称
inputobject是图片生成或编辑参数
callback_urlstring否任务完成后的回调地址，支持 http 或 https

input 参数

适用于 gemini-3.1-flash-image-preview、gemini-3-pro-image-preview、gemini-2.5-flash-image。

字段类型必填说明
promptstring是图片生成或编辑提示词
imagesstring[]否参考图 URL、data URI 或纯 base64；文生图可不传
aspect_ratiostring否宽高比，默认 1:1；支持 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9
image_sizestring否图片尺寸，默认 1K；支持 512、1K、2K、4K
ninteger否生成数量，默认 1；系统会拆成多次图片调用执行，批量任务可能返回 partial_completed

适用于 gpt-image-2。

字段类型必填说明
promptstring是图片生成或编辑提示词
imagesstring[]否参考图 URL、data URI 或纯 base64；不传时为图片生成，传入时为图片编辑
maskstring否遮罩图 URL、data URI 或纯 base64，需要 alpha 通道
sizestring否auto 或分辨率，例如 1024x1024、1536x1024
qualitystring否low、medium、high、auto
ninteger否生成数量，默认 1；系统会拆成多次图片调用执行，批量任务可能返回 partial_completed

请求示例

curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "input": {
      "prompt": "一张明亮的产品海报，玻璃水杯，白色背景",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'
curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "input": {
      "prompt": "保留主体，把背景改成雨夜霓虹街道",
      "images": [
        "https://example.com/source.png"
      ],
      "aspect_ratio": "16:9",
      "image_size": "2K"
    }
  }'
curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "一张干净的 SaaS 产品宣传图，浅色背景，真实设备展示",
      "size": "1536x1024",
      "quality": "high"
    }
  }'
curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "input": {
      "prompt": "三张不同构图的香水产品海报，干净背景，高级商业摄影",
      "aspect_ratio": "4:5",
      "image_size": "1K",
      "n": 3
    },
    "callback_url": "https://example.com/task-callback"
  }'

提交响应

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "queued",
  "created_at": 1760000000
}
字段说明
id任务唯一标识，用于后续查询
status初始状态，固定为 queued
created_at任务创建时间戳，单位秒

查询任务

curl https://cdn.12ai.org/v1/task/task_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $API_KEY"

状态说明

status说明
queued任务已提交，排队等待处理
in_progress任务正在处理中
completed全部图片成功，outputs 包含结果 URL
partial_completed部分图片成功，outputs 包含成功结果 URL，error 包含失败说明
failed全部失败，error 包含失败原因

建议轮询间隔为 3 到 5 秒。当状态为 completed、partial_completed 或 failed 时停止轮询。

查询响应示例

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "queued",
  "created_at": 1760000000
}
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "in_progress",
  "created_at": 1760000000
}
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "completed",
  "created_at": 1760000000,
  "completed_at": 1760000030,
  "outputs": [
    "https://img.12ai.org/images/task_xxxxxxxxxxxxxxxx_0.png"
  ]
}
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "partial_completed",
  "created_at": 1760000000,
  "completed_at": 1760000030,
  "outputs": [
    "https://img.12ai.org/images/task_xxxxxxxxxxxxxxxx_0.png"
  ],
  "error": "部分成功: 1/3 张图片生成成功"
}
{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "failed",
  "created_at": 1760000000,
  "completed_at": 1760000030,
  "error": "内容违反安全策略"
}

回调通知

如果提交时设置了 callback_url，任务进入 completed、partial_completed 或 failed 后，系统会向该地址发送 POST 请求。请求体与查询任务响应结构一致。

Python 轮询示例

import time
import requests

API_BASE = "https://cdn.12ai.org"
API_KEY = "sk-xxx"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

task = requests.post(
    f"{API_BASE}/v1/task/submit",
    headers=headers,
    json={
        "model": "gemini-3.1-flash-image-preview",
        "input": {
            "prompt": "一张明亮的产品海报，玻璃水杯，白色背景",
            "aspect_ratio": "1:1",
            "image_size": "1K",
            "n": 3,
        },
    },
    timeout=60,
).json()

task_id = task["id"]

while True:
    result = requests.get(
        f"{API_BASE}/v1/task/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60,
    ).json()

    status = result["status"]

    if status in ("completed", "partial_completed"):
        for url in result.get("outputs", []):
            print(url)
        break

    if status == "failed":
        raise RuntimeError(result.get("error", "任务失败"))

    time.sleep(3)

常见错误

状态码说明
400参数错误，例如缺少 model 或 input.prompt
401API Key 缺失或无效
402余额不足
403请求触发安全审核被拒绝
404任务不存在
503暂无可用渠道，可稍后重试

存量项目兼容

兼容性用法

原生请求体兼容会长期支持，适合已经接入 GPT Image 2 / OpenAI Images 或 Gemini generateContent 的存量项目。新项目建议使用上面的统一任务格式。

原请求来源迁移方式注意
GPT Image 2 JSON路径改为 /v1/task/submit，保留原字段response_format 会被忽略，结果从 outputs 读取
GPT Image 2 multipart路径改为 /v1/task/submit，继续用 image、mask 表单字段可额外传 callback_url
Gemini generateContent把模型放在顶层 model，或通过 ?model= 传入最终结果仍从 outputs 读取

Gemini SDK 固定请求路径，无法通过修改路径迁移到异步任务接口。需要异步轮询和 URL 结果时，请改用 HTTP 请求提交 /v1/task/submit。

curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一张干净的 SaaS 产品宣传图，浅色背景，真实设备展示",
    "size": "1536x1024",
    "quality": "high",
    "response_format": "url"
  }'
curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=保留主体，把背景改成明亮的现代办公室" \
  -F "image=@input.png" \
  -F "size=1024x1024" \
  -F "quality=high"
curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "contents": [{
      "parts": [
        {"text": "一张极简产品海报，白色背景，玻璃质感水杯，柔和棚拍光"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'
curl "https://cdn.12ai.org/v1/task/submit?model=gemini-3-pro-image-preview" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {"text": "一张极简产品海报，白色背景，玻璃质感水杯，柔和棚拍光"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'

GPT Image 2

OpenAI 图片接口格式的生成与编辑

Sora 视频生成

OpenAI Sora 兼容视频任务接口

On this page

接口概览推荐模型提交任务请求体input 参数请求示例提交响应查询任务状态说明查询响应示例回调通知Python 轮询示例常见错误存量项目兼容