Appearance
API 约定
本页说明所有 RouterBee API 共同遵循的规则。视频接口的完整字段请阅读创建与查询视频。
Base URL
text
https://routerbee.com/v1使用完整 URL 调用时：
text
POST https://routerbee.com/v1/videos
GET https://routerbee.com/v1/videos/{task_id}
GET https://routerbee.com/v1/videos/{task_id}/content如果 SDK 要求填写 base_url，填写 https://routerbee.com/v1，不要再额外拼接一个 /v1。
身份验证
所有公开 API 都使用 Bearer API Key：
http
Authorization: Bearer sk-你的密钥API Key 必须放在请求头中，不能放进查询字符串、请求体或 URL。建议只从服务端调用 RouterBee，不要在网页前端或移动 App 中暴露密钥。
请求格式
创建视频任务使用 JSON：
http
Content-Type: application/json
Accept: application/jsonJSON 字段名称区分大小写。未在文档中说明的字段可能被忽略、拒绝，或在上游模型升级后产生不同结果。
响应格式
普通接口返回 JSON；视频内容接口返回二进制视频流。
成功响应的 HTTP 状态通常为 200。仅判断 HTTP 状态还不够，异步视频任务仍需检查 JSON 中的 status。
请求 ID
RouterBee 会在响应头返回请求 ID：
http
X-Oneapi-Request-Id: 20260819083048...部分错误消息也会包含 request id。联系支持时请提供：
- 请求发生时间和时区
X-Oneapi-Request-Idtask_id- 已脱敏的请求体和响应体
不要提供完整 API Key。
超时设置
创建视频任务只负责提交，不会等待视频生成完成。建议客户端超时：
| 操作 | 建议超时 |
|---|---|
| 创建任务 | 60 秒 |
| 查询状态 | 30 秒 |
| 下载视频 | 120 秒或更长 |
生成本身可能需要数分钟。创建接口返回后，应保存任务 ID 并轮询状态。
重试规则
| 场景 | 是否可以重试 | 建议 |
|---|---|---|
429 | 可以 | 指数退避并加入随机抖动 |
502、503、504 | 可以 | 退避后有限次数重试 |
| 查询任务超时 | 可以 | 使用同一 task_id 重试查询 |
| 下载超时 | 可以 | 任务完成后使用同一内容地址重试 |
| 创建任务超时 | 谨慎 | 先检查任务/使用日志，避免重复创建和重复计费 |
400、401、403 | 不应直接重试 | 先修正参数、密钥、权限或额度 |
关于 Idempotency-Key
当前公开视频入口不承诺 Idempotency-Key 能在所有链路中完成去重。不要依赖这个请求头避免重复任务。创建请求发生网络超时时，应先检查控制台的任务日志和使用日志，再决定是否重新提交。
速率限制
可用并发和频率取决于账户、API Key、模型和系统策略。收到 429 后，不要立即循环重试；建议从 2 秒开始指数退避，并设置最大重试次数。