异步任务、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 若传入了不同请求参数,直接返回 HTTP 409 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 白名单未勾选该公开 model0在控制台编辑该 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 提交