跳转至

异步图片生成 (NanoBanana)

异步图片生成接口支持通过 Gemini 渠道生成图片。与同步接口不同，提交请求后立即返回任务 ID，图片在后台生成并上传至 R2 对象存储，完成后通过查询接口获取图片 URL。

何时使用异步接口

一般情况下推荐使用原生同步接口，功能更完整、响应更直接。

异步接口适用于以下场景：

  • 需要批量生成多张图片（n > 1）
  • 不希望长时间保持连接等待响应
  • 需要将图片直接存储为公开可访问的 URL（无需处理 base64）

可用模型：

模型 说明
gemini-2.5-flash-image 快速高效，适合大批量低延迟
gemini-3-pro-image-preview 专业素材制作，支持高分辨率
gemini-3.1-flash-image-preview 推荐首选，性能/成本最佳平衡

具体可用模型取决于管理员在渠道中配置的模型列表。

提交图片生成任务

POST /v1/images/async/generations

请求头

Authorization: Bearer sk-xxx
Content-Type: application/json

请求体

参数 类型 必填 说明
model string 否 模型名称，默认 gemini-2.5-flash-image
prompt string 是 图片描述文本
n integer 否 生成数量，默认 1。数量为 N 则模型会自动调用 N 次，每次独立计费
size string 否 图片尺寸，支持 OpenAI 格式或纵横比格式
quality string 否 图片质量，映射为 Gemini imageSize
images string[] 否 参考图片列表，每项可以是 URL 或 data URI（data:image/jpeg;base64,...）。用于图片编辑、风格迁移等场景
image string 否 单张参考图片（兼容 OpenAI 格式），可以是 URL 或 data URI

参考图片数量上限

不同模型的参考图片数量上限不同：

  • gemini-2.5-flash-image：最多 3 张
  • gemini-3.1-flash-image-preview：最多 14 张
  • gemini-3-pro-image-preview：最多 14 张

size 参数

支持两种格式：

OpenAI 像素格式（自动转换为纵横比）：

值 纵横比
256x256 / 512x512 / 1024x1024 1:1
1536x1024 3:2
1024x1536 2:3
1024x1792 9:16
1792x1024 16:9

纵横比格式（直接传递给 Gemini）：

1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 等

quality 参数

值 Gemini imageSize
standard / medium / low / auto / 1K 1K
hd / high / 2K 2K
4K 4K

请求示例

curl -X POST https://cdn.12ai.org/v1/images/async/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A cute cat playing in the sunshine, photorealistic style",
    "size": "16:9",
    "quality": "hd"
  }'

curl -X POST https://cdn.12ai.org/v1/images/async/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "Add a wizard hat to the cat in this image",
    "images": [
      "https://example.com/cat.jpg"
    ]
  }'

也支持 data URI 格式：

{
  "model": "gemini-3-pro-image-preview",
  "prompt": "Transform this photo into Van Gogh style",
  "images": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  ]
}

响应

{
  "id": "task_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "status": "pending",
  "model": "gemini-3.1-flash-image-preview",
  "created_at": 1711008000
}
字段 说明
id 任务 ID，用于后续查询
status 固定为 pending
model 使用的模型名称
created_at 创建时间（Unix 时间戳）

查询任务状态

GET /v1/images/async/generations/{task_id}

请求头

Authorization: Bearer sk-xxx

响应 — 处理中

任务仍在生成或上传图片时：

{
  "id": "task_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "status": "pending",
  "model": "gemini-3.1-flash-image-preview",
  "created_at": 1711008000
}

响应 — 成功

图片生成完成并上传至 R2：

{
  "id": "task_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "status": "complete",
  "model": "gemini-3.1-flash-image-preview",
  "created_at": 1711008000,
  "data": [
    {
      "url": "https://img.example.com/images/req_abc123_0.png"
    }
  ]
}
字段 说明
data 图片数组，每项包含一个 url 字段
data[].url 图片的公开访问 URL（R2 存储）

响应 — 部分成功

当 n > 1 时，部分图片生成成功、部分失败。成功的图片正常返回，失败部分的额度自动退还：

{
  "id": "task_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "status": "partial_complete",
  "model": "gemini-3.1-flash-image-preview",
  "created_at": 1711008000,
  "data": [
    {
      "url": "https://img.example.com/images/req_abc123_0.png"
    }
  ],
  "error": {
    "message": "部分成功: 1/3 张图片生成成功"
  }
}

响应 — 失败

全部图片生成失败时（额度会全部自动退还）：

{
  "id": "task_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "status": "failed",
  "model": "gemini-3.1-flash-image-preview",
  "created_at": 1711008000,
  "error": {
    "message": "上游 API 错误 (HTTP 400): User location is not supported..."
  }
}

状态说明

status 说明
pending 任务已提交，正在排队或生成中
complete 全部图片生成成功，data 中包含所有图片 URL
partial_complete 部分成功（n > 1 时），data 中包含成功的图片，error.message 描述成功/失败数量，失败部分额度已退还
failed 全部生成失败，error.message 中包含原因，额度已全部自动退还

计费说明

  • 提交时按 模型单价 × N 预扣费
  • 全部成功：扣费生效
  • 部分成功：仅扣成功部分的费用，**自动退还**失败部分的额度
  • 全部失败：**全额退还**预扣额度

完整调用示例

Python

import requests
import time

API_BASE = "https://cdn.12ai.org"
API_KEY = "sk-xxx"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. 提交任务
resp = requests.post(f"{API_BASE}/v1/images/async/generations", headers=HEADERS, json={
    "model": "gemini-3.1-flash-image-preview",
    "prompt": "A futuristic city at sunset, cinematic lighting",
    "size": "16:9",
    "quality": "hd"
})
task = resp.json()
task_id = task["id"]
print(f"任务已提交: {task_id}")

# 2. 轮询查询
while True:
    result = requests.get(
        f"{API_BASE}/v1/images/async/generations/{task_id}",
        headers=HEADERS
    ).json()

    if result["status"] == "complete":
        for img in result["data"]:
            print(f"图片 URL: {img['url']}")
        break
    elif result["status"] == "partial_complete":
        print(f"部分成功: {result['error']['message']}")
        for img in result["data"]:
            print(f"图片 URL: {img['url']}")
        break
    elif result["status"] == "failed":
        print(f"生成失败: {result['error']['message']}")
        break
    else:
        print("生成中...")
        time.sleep(3)

cURL

# 提交任务
TASK_ID=$(curl -s -X POST https://cdn.12ai.org/v1/images/async/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-2.5-flash-image","prompt":"A beautiful mountain landscape"}' \
  | jq -r '.id')

echo "Task ID: $TASK_ID"

# 查询结果（等待几秒后）
sleep 5
curl -s https://cdn.12ai.org/v1/images/async/generations/$TASK_ID \
  -H "Authorization: Bearer sk-xxx" | jq .

错误码

HTTP 状态码 说明
400 请求参数错误（如缺少 prompt）或 R2 未配置
401 认证失败
404 任务不存在
503 无可用渠道