12API logo12API

异步图片任务

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

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

什么时候用异步接口

如果能接受同步等待，可以使用 NanoBanana 图片 或 GPT Image。需要提交后轮询、后台处理或批量任务管理时，使用本页接口。GPT Image 同步接口也支持返回 URL，无需仅为获取 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-2.5-sunburst注重编辑精度，适合商业海报、精细产品图和反复编辑；生成耗时更长
gpt-image-2.5-flare兼顾画质与速度，适合日常出图、批量生成和创意原型
gpt-image-2上一代基线模型，适合已接入的项目

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

GPT Image 系列

gpt-image-2、gpt-image-2.5-sunburst 和 gpt-image-2.5-flare 使用相同的任务结构，但两个 2.5 模型额外支持 quality: "xhigh" 和 "max"。切换回 gpt-image-2 时，请将这两个档位改为 low、medium、high 或 auto。模型定位参考 OpenAI 官方介绍。

提交任务

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

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、gpt-image-2.5-sunburst、gpt-image-2.5-flare。

字段类型必填说明
promptstring是图片生成或编辑提示词
imagesstring[]否参考图 URL、data URI 或纯 base64；不传时为图片生成，传入时为图片编辑
maskstring否遮罩图 URL、data URI 或纯 base64，需要 alpha 通道
sizestring否auto 或分辨率，例如 1024x1024、1536x1024
qualitystring否默认 auto；所有 GPT Image 模型支持 low、medium、high、auto，两个 2.5 模型额外支持 xhigh、max
backgroundstring否不传时使用默认背景处理；传 transparent 时请求透明背景（预览）
output_formatstring否png、webp 或 jpeg，默认 png
ninteger否生成数量，默认 1；系统会拆成多次图片调用执行，批量任务可能返回 partial_completed

设置 background: "transparent" 时，输出格式必须为 png 或 webp，不能使用 jpeg。output_format 可以省略，此时默认使用 png。

异步任务把质量档位放在 input.quality 中，图片生成与编辑均适用。完整档位、选择建议及官方来源见 GPT Image 的 quality 参数。

size 的尺寸限制和推荐分辨率见 GPT Image 的 size 参数。mask 必须与第一张参考图尺寸一致，并包含 alpha 通道；多张参考图时只应用于第一张图。

请求示例

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": "gpt-image-2",
    "input": {
      "prompt": "保留图片主体，移除背景并输出透明背景",
      "images": [
        "https://example.com/source.png"
      ],
      "size": "1024x1024",
      "quality": "high",
      "background": "transparent",
      "output_format": "png"
    }
  }'
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.5-flare",
    "input": {
      "prompt": "一张干净的 SaaS 产品宣传图，浅色背景，真实设备展示",
      "size": "1536x1024",
      "quality": "xhigh"
    }
  }'
curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "input": {
      "prompt": "一张高端护肤品的商业海报，柔和棚拍光，细节清晰",
      "size": "2048x2048",
      "quality": "max",
      "output_format": "png"
    },
    "callback_url": "https://example.com/task-callback"
  }'
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 / OpenAI Images 或 Gemini generateContent 的存量项目。新项目建议使用上面的统一任务格式。

原请求来源迁移方式注意
GPT Image JSON路径改为 /v1/task/submit，保留原字段response_format 会被忽略，结果从 outputs 读取
GPT Image multipart路径改为 /v1/task/submit，继续用 image[]、mask 表单字段多张图片时重复传入 image[]；可额外传 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"
      }
    }
  }'

On this page

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