异步任务、30 天结果链接与错误码
图像与视频生成统一采用异步任务机制,内置 24 小时防重复提交保护、30 天有效 HTTPS 结果链接交付以及失败全额退回机制。
POST /v1/{images,videos}/generations → GET /v1/tasks/:task_id
任务状态说明与轮询建议
生成接口完成参数校验、锁定当前单价并按规格上限临时预扣积分后,立即返回 HTTP 202 Accepted 与 task_... 任务 ID。图像任务建议每 2 秒 查询一次 GET /v1/tasks/:task_id,视频任务建议每 3–5 秒 查询一次,直至状态变为 completed 或 failed。
| 状态值 | 最终状态 | 含义与积分状态 |
|---|---|---|
| pending | 否 | 请求已受理并临时预扣规格上限积分,正在排队等待执行。 |
| processing | 否 | 模型正在渲染生成并准备输出文件。 |
| completed | 是 | 生成结果已就绪;按实扣减 usage.cost_credits、退回未用预扣额度,并返回 results[0].url 下载链接。 |
| failed | 是 | 任务终止并返回结构化 error.code;预扣积分 100% 自动退回(实扣 0 积分)。 |
{
"id": "task_01e561ba-859e-47fe-be79-60bc6f1d6499",
"model": "gpt-image-2.6-flare",
"object": "image.generation.task",
"status": "pending",
"created_at": "2026-11-15T09:49:18.000Z"
}防重复提交与 30 天结果链接
建议每次发起 POST 生成请求时附带业务侧唯一的 Idempotency-Key 请求头(例如订单号或 UUID):
- 网络超时安全重试(24 小时窗口):客户端超时重发相同
Idempotency-Key与相同请求体时,直接返回原任务当前状态,不会重复提交或二次扣费。 - 参数不一致拦截:同一
Idempotency-Key若传入了不同请求参数,直接返回 HTTP409 idempotency_conflict(0 扣费)。 - 30 天有效结果下载链接(
files.callmodels.dev):每个完成的results[i].url均带有 30 天有效签名(expires+sig),无需附带 API Key 即可直接在页面渲染或由服务端下载;如需超过expires_at长期保存,请转存至自有存储。
错误码速查与安全重试规范
所有非 2xx 同步拦截与异步 failed 任务均返回统一结构 { "error": { "code", "message", "retryable" } } 及 X-Request-Id 追踪头。任何失败均不扣费。
| 状态码 / 错误码 | 触发原因 | 扣费 | 处理与重试建议 |
|---|---|---|---|
| 400 invalid_parameter | 未知字段、非法枚举或无效图片链接 | 0 | 修正请求参数后再发起请求 |
| 401 invalid_api_key | 缺失、格式错误、已吊销或已过期密钥 | 0 | 前往控制台轮换有效密钥 |
402 insufficient_balance402 key_quota_exceeded | 账户可用积分或该 Key 限额低于预占上限 | 0 | 充值账户积分或调高该 Key 配额上限 |
| 403 model_not_allowed | 当前 Key 白名单未勾选该公开 model | 0 | 在控制台编辑该 Key 的模型白名单 |
| 409 idempotency_conflict | 同一 Idempotency-Key 传入了不同参数 | 0 | 不同请求体请生成新的 Idempotency-Key |
429 rate_limited503 service_unavailable | 并发速率限制或服务瞬时繁忙 | 0 | 保留原 Idempotency-Key 指数退避重试 |
Task: submission_rejectedTask: upstream_failedTask: timeout | 内容安全拦截、参考图不可访问、模型生成失败或执行超时 | 0 | 预扣已全额退回;检查输入后换新 Idempotency-Key 提交 |