同步请求和异步请求
图片接口的两种调用方式:一次请求等到出图,或者加 async true 立刻拿到任务号,再用一个轮询请求查一个或多个任务,也可以用回调通知。
生成图片有两种调用方式。两者参数相同、价格相同、限制也是同一套,每次请求都可以自己选。
| 同步(默认) | 异步 | |
|---|---|---|
| 怎么用 | 发出请求后等着 | 加 async: true,立刻拿到任务号 |
| 结果什么时候来 | 同一个响应里,等 20 秒到几分钟 | 之后:你来轮询,或者我们回调通知 |
| 连接占用多久 | 一直到出图 | 不到 1 秒 |
| 单次最长运行 | 7 分钟 | 10 分钟 |
| 返回 | 图片数据(b64_json)或链接(url) | 链接(url) |
| 兼容 | OpenAI 官方 SDK,以及所有按 OpenAI 图片接口写的工具 | 任何 HTTP 客户端 |
| 适合 | 脚本、后端服务、一次一张 | 网页、一次很多张、慢模型、运行时间受限的云函数 |
三个接口
| 接口 | 作用 |
|---|---|
POST /v1/images/generations 或 /v1/images/edits,带 async: true | 创建任务,返回 202 和任务号 |
GET /v1/images/tasks?ids=a,b,c | 一次查询最多 100 个任务的状态 |
GET /v1/images/tasks/{id} | 查询单个任务的状态 |
1. 创建任务
在 POST /v1/images/generations 的请求体里加 async: true;POST /v1/images/edits 则作为一个表单字段。
curl https://api.cheapestimagen.com/v1/images/generations \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-image-2.6", "prompt": "雪地里的一只红狐狸", "async": true}'不到 1 秒就返回 202 Accepted:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "in_progress",
"created": 1795062073,
"finished": null,
"model": "gpt-image-2.6"
}把 id 存下来。有三点要知道:
- 只返回链接。 任务的图片以链接返回,所以
response_format不填或填url。填b64_json会返回400。 - 跑不了的请求当场报错,不会拖到后面。 参数不对(
400)、积分不够(402)、请求太多(429),都和同步请求一样立刻返回错误,不会创建任务。 - 没法加请求体字段? 用请求头
Prefer: respond-async,效果和async: true相同。
2. 查询任务
一次查多个任务
同时在等多个任务时,一次全部查完。页面创建了 10 个任务,就发 1 个轮询请求,而不是 10 个。
curl "https://api.cheapestimagen.com/v1/images/tasks?ids=req_33ac10d3e9a8e6f120f4c0d3,req_26e50328772b7d62f59d355a" \
-H "Authorization: Bearer YOUR_KEY"{
"object": "list",
"data": [
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "succeeded",
"created": 1795062073,
"finished": 1795062098,
"model": "gpt-image-2.6",
"result": {
"created": 1795062098,
"data": [{ "url": "https://img.cheapestimagen.com/g/req_33ac10d3e9a8e6f120f4c0d3/0.png" }]
}
},
{
"id": "req_26e50328772b7d62f59d355a",
"object": "image.task",
"status": "in_progress",
"created": 1795062074,
"finished": null,
"model": "gpt-image-2.6"
}
],
"not_found": []
}ids最多传 100 个任务号,用逗号分隔。data里的任务顺序和你传的顺序一致。- 不属于你账户的任务号,或者图片已过保存期的任务,会列在
not_found里,不会让整个请求失败。
查单个任务
curl https://api.cheapestimagen.com/v1/images/tasks/req_33ac10d3e9a8e6f120f4c0d3 \
-H "Authorization: Bearer YOUR_KEY"直接返回这一个任务对象。任务号不存在时返回 404。
任务的三种状态
status | 含义 | 多出来的字段 |
|---|---|---|
in_progress | 图片还在生成 | 无 |
succeeded | 已完成 | result:和同步调用返回的内容完全一样,{ created, data: [{ url }] } |
failed | 没成功 | error:和同步调用返回的错误完全一样 |
失败的任务长这样:
{
"id": "req_33ac10d3e9a8e6f120f4c0d3",
"object": "image.task",
"status": "failed",
"created": 1795062073,
"finished": 1795062110,
"model": "gpt-image-2.6",
"error": { "message": "The image provider failed. You were not charged.", "type": "api_error", "param": null, "code": "upstream_error" }
}失败的任务不扣费。唯一的例外和同步请求相同:Nano Banana 稳定通道被内容检查拒绝。
多久查一次
每 2 到 5 秒查一次就够了。查询任务不收费,也不算生图请求,不占“进行中的请求”名额。任务可以查 72 小时,也就是图片的保存期。
示例:网页一次提交 10 张图
创建任务时每张图一个请求,之后每 3 秒用一个请求查全部。
const API = "https://api.cheapestimagen.com/v1";
const headers = { Authorization: "Bearer YOUR_KEY", "Content-Type": "application/json" };
// 创建 10 个任务
const prompts = Array.from({ length: 10 }, (_, i) => `雪地里的一只红狐狸,第 ${i + 1} 版`);
const started = await Promise.all(prompts.map((prompt) =>
fetch(`${API}/images/generations`, {
method: "POST", headers,
body: JSON.stringify({ model: "gpt-image-2.6", prompt, async: true }),
}).then((r) => r.json())
));
// 用一个请求轮询全部任务,直到没有进行中的
let waiting = started.map((t) => t.id);
const done = {};
while (waiting.length) {
await new Promise((r) => setTimeout(r, 3000));
const { data } = await fetch(`${API}/images/tasks?ids=${waiting.join(",")}`, { headers }).then((r) => r.json());
for (const task of data) if (task.status !== "in_progress") done[task.id] = task;
waiting = waiting.filter((id) => !done[id]);
}
for (const task of Object.values(done)) {
console.log(task.status === "succeeded" ? task.result.data[0].url : task.error.message);
}不要把 API 密钥写在公开的网页里。应该由你自己的服务器调用接口,网页只和你的服务器通信。
示例:Python
import time, requests
API = "https://api.cheapestimagen.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_KEY"}
ids = [
requests.post(f"{API}/images/generations", headers=HEADERS, json={
"model": "gpt-image-2.6", "prompt": f"雪地里的一只红狐狸,第 {i} 版", "async": True,
}).json()["id"]
for i in range(10)
]
done = {}
while len(done) < len(ids):
time.sleep(3)
waiting = [i for i in ids if i not in done]
tasks = requests.get(f"{API}/images/tasks", headers=HEADERS, params={"ids": ",".join(waiting)}).json()["data"]
done.update({t["id"]: t for t in tasks if t["status"] != "in_progress"})
for t in done.values():
print(t["result"]["data"][0]["url"] if t["status"] == "succeeded" else t["error"]["message"])用 OpenAI SDK 时,通过 extra_body={"async": True} 传这个字段,查询任务用普通的 HTTP 请求。
不想轮询:回调通知
加上 webhook_url,任务结束时我们会把任务内容 POST 到这个地址:
{ "model": "gpt-image-2.6", "prompt": "雪地里的一只红狐狸", "async": true, "webhook_url": "https://example.com/hooks/images" }- 地址必须是公网域名上的
https://地址。 - 请求体就是任务对象,和
GET /v1/images/tasks/{id}返回的 JSON 相同。 - 请在 10 秒内返回任意
2xx。否则我们会在 3 秒和 15 秒后各再试一次,然后停止。 - 想让回调带签名,就在请求里加一个你自己定的密钥
webhook_secret(16 到 128 个字符)。不加的话回调没有签名:请把它当作通知,取出里面的id,用你的密钥再查一次任务,以查到的内容为准。 - 不管回调有没有送达,任务都能照常查询,所以漏掉一次回调不会丢结果。
校验签名
带了 webhook_secret 时,回调请求会有一个请求头 x-webhook-signature: t=1763560000,v1=5f2b…。t 是发出回调的时间(Unix 秒),v1 是用你的密钥对文本 <t>.<请求体> 做 HMAC-SHA256 得到的十六进制串。你用收到的原始请求体算出同样的值来比对;t 距离现在超过几分钟的请求直接拒绝。
import hashlib, hmac, time
def is_ours(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300import { createHmac, timingSafeEqual } from 'node:crypto';
function isOurs(secret, header, rawBody) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
}请求体要用收到时的原样,不要先解析成 JSON 再序列化。这个密钥只用于这一次请求,不会保存到你的账户里。
限制
异步请求和同步请求一样计数:每个账户每分钟 300 个请求、同时 50 个进行中。已有 50 个在跑时再提交会返回 429,等其中一个结束再提交。查询任务不计数。
Idempotency-Key 的用法不变:带同一个值的请求还在运行或已经成功时,重复提交会返回 409。