异步图片任务¶

异步图片任务适合批量生成、后台处理、长耗时图片任务，以及需要直接获取图片 URL 的场景。提交任务后接口立即返回任务 ID，生成完成后通过查询接口获取结果，也可以通过 callback_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}`

Base URL：https://cdn.tweapi.com

所有接口都使用：

Authorization: Bearer $API_KEY

提交任务¶

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

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

请求体¶

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

input 参数¶

NanoBananaGPT Image

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

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

适用于 gpt-image-2、gpt-image-2.5-sunburst、gpt-image-2.5-flare。

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

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

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

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

请求示例¶

NanoBananaGPT 透明背景参考图编辑GPT FlareGPT Sunburst批量与回调

curl https://cdn.tweapi.com/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.tweapi.com/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.tweapi.com/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.tweapi.com/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.tweapi.com/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.tweapi.com/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.tweapi.com/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://example.com/images/task_xxxxxxxxxxxxxxxx_0.png"
  ]
}

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "partial_completed",
  "created_at": 1760000000,
  "completed_at": 1760000030,
  "outputs": [
    "https://example.com/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.tweapi.com"
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`
`401`	API 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。

GPT JSONGPT multipartGemini JSONGemini query

curl https://cdn.tweapi.com/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.tweapi.com/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.tweapi.com/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.tweapi.com/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"
      }
    }
  }'

模型	适合场景
`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`	上一代基线模型，适合已接入的项目