异步任务与素材下载
生图耗时较长时,可以在图片生成或图片编辑请求里加 "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. 提交任务
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
{
"task_id": "img_9b1c0e6d2f7a4c3b8e5d1a0f6c2b4e7d",
"status": "QUEUED",
"progress": "0%",
"created": 1793966400
}
编辑接口同理:JSON 请求体加 "async": true,multipart 加 -F 'async=true'。
2. 轮询直到结束并保存图片
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同时使用,否则返回 400async 不支持 stream,请关闭流式返回
适用范围: 异步目前只适用于 GPT Image、DALL·E 等 OpenAI 系列图片模型。Gemini、Imagen 等其他模型提交时仍会返回 task_id,但任务随后会变为 FAILURE 并退还额度,请改用同步请求。
状态流转
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查询
查询任务
GET /v1/images/tasks/{task_id}
任务归属于账号:同一账号下的任意 API Key 都能查询;其他账号的任务一律返回 404。
成功示例:
{
"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)
失败时响应只有状态,没有失败原因字段:
{
"task_id": "img_9b1c0e6d2f7a4c3b8e5d1a0f6c2b4e7d",
"status": "FAILURE",
"progress": "100%",
"submit_time": 1793966400,
"finish_time": 1793966470
}
需要了解原因时,把 task_id 提供给客服排查。
下载素材
GET /v1/materials/{asset_key}/content
data[].url 形如 https://www.nextai-code.com/v1/materials/{asset_key}/content 时,表示图片已保存在你账号的素材库。用同一账号下的任意 API Key 下载:
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 无效、额度不足等鉴权错误见错误码。