跳转到主要内容
ByteSpike 多模态目录（Sora 2、Veo 3.1、Seedance、Seedream、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

curl https://llm.bytespike.ai/v1/tasks/submit \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "sora-2-pro",
    "out_task_id": "my-render-2026-05-25-001",
    "params": {
      "prompt": "A timelapse of a city skyline at sunset, 16:9, 1080p, 8 seconds",
      "duration_seconds": 8,
      "aspect_ratio": "16:9"
    },
    "callback_url": "https://my-app.example.com/bytespike/webhook"
  }'

​
Headers

HeaderRequiredNotes
AuthorizationyesBearer sk-byts-…（这个端点也接受 Anthropic 风格的 x-api-key）。
content-typeyesapplication/json。

​
Body

FieldTypeRequiredNotes
modelstringyes目录 slug —— 见 Models。tasks 端点只接受多模态模型（image/video）。文本模型会被 400 invalid_param 拒掉。
paramsobjectyes模型特定参数。结构镜像底层 provider —— 例如 Sora 2 是 prompt、duration_seconds、aspect_ratio；Seedream 是 prompt、n、size。各模型详情见 API 参考 → Image / Video。
out_task_idstringno你的幂等键。用相同 model + params 重复提交同一个 out_task_id 会返回已存在的任务（200）。重复 out_task_id 但参数冲突返回 409 duplicate_out_task_id。
callback_urlstringno任务进入终态时网关 POST 通知的 webhook。
streambooleanno为 /tasks/stream/{task_id} SSE 投递保留。本端点忽略此字段。

​
Body 大小上限

/v1/tasks/* 的 body 上限为 1 MiB。对任何合理的 params 结构都够用， 甚至包含小的 data:image/...;base64,... 内联图像。更大的输入应该先 上传到 URL，然后在 params 里传 URL。

​
Response

{
  "task_id": "task_01HQX9F2P6Y8VEX3CRZ8GXJVD9",
  "out_task_id": "my-render-2026-05-25-001",
  "status": "pending",
  "estimated_credits": 1.50,
  "estimated_seconds": 35
}

​
Response 字段

FieldTypeNotes
task_idstring服务端生成的 ULID。/tasks/query 和 /tasks/cancel 都用它。
out_task_idstring你传了的话原样回显。否则省略。
statusstringpending、running、completed、failed、cancelled 之一。submit 时永远是 pending。
estimated_creditsnumberprovider 的预估成本，单位 credits。如果 provider 不返回，则省略。最终扣费用 /tasks/query 的 credits_used。
estimated_secondsintegerprovider 的预估 ETA，单位秒。用来设定轮询节奏。未知则省略。

​
任务生命周期

pending  →  running  →  completed
                    ↘
                       failed
                    ↘
                       cancelled (via /tasks/cancel)
  • pending —— 派发器已接受请求，尚未开始生成
  • running —— 模型正在生成
  • completed —— output 已填，扣费定稿
  • failed —— error_code + error_message 已填，不计费
  • cancelled —— 用户在终态前调用了 /tasks/cancel

​
错误

所有错误使用 OpenAI envelope 结构（即使用 x-api-key 调用也是）。 
{
  "error": {
    "code": "invalid_param",
    "message": "model \"claude-sonnet-4-6\" is not a multimodal task model",
    "type": "invalid_request_error"
  }
}
HTTPcode触发时机
400invalid_paramJSON 错、model 不支持、缺必填字段。
401invalid_api_keykey 缺失 / 已撤销 / 已禁用。
409duplicate_out_task_id已存在的任务 out_task_id 相同但 params 不同。
413request_entity_too_largeBody > 1 MiB。把内联 base64 改用 URL。
429rate_limit_exceeded见 Pricing 的速率限制章节。
500internal_errorprovider 端或网关端故障。重试。

​
幂等

out_task_id 就是你的幂等键。派发器按 (api_key_id, out_task_id) 元组 去重。相同组合 + 相同 params 重复提交会返回原 task_id 和当前状态 —— 对重试安全的客户端代码很有用：网络抖动也不会重复出图。

​
价格

按秒计（视频）/ 按次计（图像）。完整实时费率表见 bytespike.ai/pricing —— 只在 completed 时扣费；failed 和 cancelled 任务免费。

​
下一步