/images/generations 和 /messages
这种同步端点会阻塞到模型返回;tasks 端点不会 —— submit 接受你的请求,
毫秒级返回 task_id,真正的生成在服务端跑。然后 polling
/tasks/query,或通过 SSE 在 /tasks/stream/{task_id}
上订阅状态变化。
何时选用
- 视频生成 —— 每个视频模型都是长跑(10–60s+),tasks/submit 是 唯一合理的形状
- 批量图像生成 —— fire-and-forget;几分钟后再对账结果
- 高并发生产者 —— 让 worker 池不被 HTTP keep-alive 卡住
callback_url集成 —— 注册一个 webhook 就完全不用轮询
/messages、/chat/completions、/responses)请用同步端点。
tasks 只用于多模态长尾。
Request
Headers
Body
Body 大小上限
/v1/tasks/* 的 body 上限为 1 MiB。对任何合理的 params 结构都够用,
甚至包含小的 data:image/...;base64,... 内联图像。更大的输入应该先
上传到 URL,然后在 params 里传 URL。
Response
Response 字段
任务生命周期
pending—— 派发器已接受请求,尚未开始生成running—— 模型正在生成completed——output已填,扣费定稿failed——error_code+error_message已填,不计费cancelled—— 用户在终态前调用了/tasks/cancel
错误
所有错误使用 OpenAI envelope 结构(即使用x-api-key 调用也是)。
幂等
out_task_id 就是你的幂等键。派发器按 (api_key_id, out_task_id) 元组
去重。相同组合 + 相同 params 重复提交会返回原 task_id 和当前状态 ——
对重试安全的客户端代码很有用:网络抖动也不会重复出图。
价格
按秒计(视频)/ 按次计(图像)。完整实时费率表见 bytespike.ai/pricing —— 只在completed 时扣费;failed 和 cancelled 任务免费。
下一步
POST /tasks/query—— 读任务当前状态POST /tasks/cancel—— 终止未终态任务