Skip to main content
ByteSpike 多模态目录(Veo 3.1、Nano Banana、GPT Image……)的异步派发入口。 像 /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 时扣费;failedcancelled 任务免费。

下一步