异步任务与素材下载

生图耗时较长时,可以在图片生成或图片编辑请求里加 "async": true:平台立即返回 task_id,不必一直保持长连接,之后再轮询任务结果。本页还说明如何下载结果中的 /v1/materials/.../content 素材地址。

操作 方法与路径
提交异步任务 POST /v1/images/generations 或 POST /v1/images/edits,请求体加 async: true
查询任务 GET /v1/images/tasks/{task_id}
下载素材 GET /v1/materials/{asset_key}/content

三个接口都用同一种鉴权:Authorization: Bearer YOUR_API_KEY。

快速示例

1. 提交任务

BASH
curl https://www.nextai-code.com/v1/images/generations \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一座薄荷绿色的小房子,插画风格",
    "output_format": "png",
    "n": 1,
    "async": true
  }' \
  -o image-task.json
JSON
{
  "task_id": "img_9b1c0e6d2f7a4c3b8e5d1a0f6c2b4e7d",
  "status": "QUEUED",
  "progress": "0%",
  "created": 1793966400
}

编辑接口同理:JSON 请求体加 "async": true,multipart 加 -F 'async=true'。

2. 轮询直到结束并保存图片

BASH
python3 - <<'PY'
import base64, json, os, time
from pathlib import Path
from urllib.request import Request, urlopen

BASE = "https://www.nextai-code.com/v1"
key = os.environ["NEXTAI_API_KEY"]
task_id = json.loads(Path("image-task.json").read_text())["task_id"]

def get(url):
    with urlopen(Request(url, headers={"Authorization": f"Bearer {key}"}), timeout=60) as r:
        return r.read()

deadline = time.monotonic() + 15 * 60
while time.monotonic() < deadline:
    task = json.loads(get(f"{BASE}/images/tasks/{task_id}"))
    if task["status"] == "SUCCESS":
        for i, image in enumerate(task["data"]["data"], start=1):
            if image.get("b64_json"):
                content = base64.b64decode(image["b64_json"])
            else:
                content = get(image["url"])  # 素材地址,需带 API Key
            Path(f"task-image-{i}.png").write_bytes(content)
            print(f"task-image-{i}.png")
        break
    if task["status"] == "FAILURE":
        raise SystemExit(f"任务失败,task_id={task_id}")
    time.sleep(5)
else:
    raise SystemExit(f"等待超时,任务可能仍在执行,稍后用 task_id={task_id} 继续查询")
PY

查询报错或等待超时时,保留 task_id 继续查询即可,不要重新提交,否则会再生成一次并再计费一次。

异步任务

什么时候会返回异步

只有请求里显式写了 async: true 才走异步,默认都是同步。async 是平台自己的开关,不会转发给模型服务商。

  • JSON 中 async 不区分大小写(Async、ASYNC 同样生效)
  • multipart 中 async 必须是可解析的布尔值(true / false / 1 / 0),空值或其他内容返回 400
  • async: true 不能与 stream: true 同时使用,否则返回 400 async 不支持 stream,请关闭流式返回

适用范围: 异步目前只适用于 GPT Image、DALL·E 等 OpenAI 系列图片模型。Gemini、Imagen 等其他模型提交时仍会返回 task_id,但任务随后会变为 FAILURE 并退还额度,请改用同步请求。

状态流转

CODE
QUEUED (0%) ──► IN_PROGRESS (10%) ──► SUCCESS (100%)
                                  └─► FAILURE (100%)
status progress 含义 客户端处理
QUEUED 0% 已入队,等待执行 继续轮询
IN_PROGRESS 10% 正在生成 继续轮询;进度不会逐步增长,执行期间一直是 10%
SUCCESS 100% 已生成,结果在 data 中 停止轮询,读取结果
FAILURE 100% 失败,额度已退还 停止轮询,保留 task_id 供排查

计费:提交时预扣额度;SUCCESS 时按预扣金额结算,FAILURE 时全额退还。

轮询建议

  • 建议每 5 秒查询一次,总等待上限设为 15 分钟左右;单个任务的生成时间不超过 10 分钟,超时会变为 FAILURE
  • 查询接口不收费,但请不要高频轮询
  • 等待超时不等于任务被取消,可以稍后继续用同一个 task_id 查询

查询任务

CODE
GET /v1/images/tasks/{task_id}

任务归属于账号:同一账号下的任意 API Key 都能查询;其他账号的任务一律返回 404。

成功示例:

JSON
{
  "task_id": "img_9b1c0e6d2f7a4c3b8e5d1a0f6c2b4e7d",
  "status": "SUCCESS",
  "progress": "100%",
  "submit_time": 1793966400,
  "finish_time": 1793966460,
  "data": {
    "created": 1793966455,
    "data": [
      {
        "b64_json": "BASE64_IMAGE_DATA",
        "url": "https://www.nextai-code.com/v1/materials/AbC123xyz/content"
      }
    ]
  }
}
字段 类型 说明
task_id string 任务 ID,以 img_ 开头
status string QUEUED / IN_PROGRESS / SUCCESS / FAILURE
progress string 见状态表
submit_time integer 提交时间,Unix 秒
finish_time integer 完成时间,Unix 秒;未结束时省略
data object 完整的图片响应,结构同同步响应,仅 SUCCESS 时出现
data.data[] array 图片数组,结构同同步响应的 data[]

注意两点:

  • 图片数组在 data.data[],比同步响应多一层
  • 平台会把每张图保存到素材库,并把该项的 url 设为素材地址;因此同一项可能同时有 b64_json 和 url。个别保存失败的项保持模型服务商的原样返回(只有 base64,或模型服务商的 URL)

失败时响应只有状态,没有失败原因字段:

JSON
{
  "task_id": "img_9b1c0e6d2f7a4c3b8e5d1a0f6c2b4e7d",
  "status": "FAILURE",
  "progress": "100%",
  "submit_time": 1793966400,
  "finish_time": 1793966470
}

需要了解原因时,把 task_id 提供给客服排查。

下载素材

CODE
GET /v1/materials/{asset_key}/content

data[].url 形如 https://www.nextai-code.com/v1/materials/{asset_key}/content 时,表示图片已保存在你账号的素材库。用同一账号下的任意 API Key 下载:

BASH
curl https://www.nextai-code.com/v1/materials/ASSET_KEY/content \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  --fail-with-body -o image.png
项 说明
查询参数 download=1 响应带 Content-Disposition: attachment,浏览器会以文件下载
Content-Type 图片为 image/*;无法识别时为 application/octet-stream。按它决定保存后缀
缓存 响应带 Cache-Control: private, no-store,请自行保存

如果拿到的是 /v1/materials/... 开头的相对路径,在前面拼上 https://www.nextai-code.com 即可。

什么时候会给出素材地址

场景 返回中的 url
同步请求,模型返回 URL 通常为素材地址;个别保存失败时为模型服务商的原地址
同步请求,模型返回 base64 响应里只有 b64_json,没有素材地址
异步任务 通常同时有 b64_json 和素材地址(见上文)

模型服务商的原地址(非 nextai-code.com 域名)不要带 NextAI Code 的 API Key 去请求,直接下载即可,这类地址通常是临时的。

有效期

素材是私有的,只有所属账号能读取,保留期有限(默认 30 天),到期后自动清理。过期、已删除或不属于当前账号时返回 404。需要长期保留的图片请及时下载到自己的存储。

错误

查询任务接口的错误为 OpenAI 格式:

情况 HTTP error.code
task_id 为空 400 invalid_request
任务不存在,或不属于当前账号 404 task_not_exist
平台查询失败 500 get_task_failed,可稍后重试

素材下载接口的错误体格式不同,为 {"success": false, "message": "..."}:

情况 HTTP message
素材不存在 / 已删除 / 不属于当前账号 404 素材不存在
素材已过期 404 素材不存在或已过期
暂时读取失败 502 读取素材内容失败,请稍后重试

502 可稍后重试。API Key 无效、额度不足等鉴权错误见错误码。

相关文档