创建与查询视频

RouterBee 视频 API 是异步接口。一次完整调用分为四步：

1. 调用 POST /v1/videos 创建任务。
2. 保存响应中的 task_id。
3. 调用 GET /v1/videos/{task_id} 轮询状态；状态为 queued 或 in_progress 时继续等待。
4. 状态为 completed 时调用 GET /v1/videos/{task_id}/content 下载视频；状态为 failed 时读取 error 并停止。

以下 JSON 中的 your-model-id 是占位符。先在模型广场查看所选模型的接口、参数和当前价格，再用当前 API Key 的 GET /v1/models 确认调用权限。尺寸、时长和参考素材示例不代表所有模型都支持。

创建视频任务

POST https://routerbee.com/v1/videos
Authorization: Bearer $ROUTERBEE_API_KEY
Content-Type: application/json

最小请求

{
  "model": "your-model-id",
  "prompt": "A bee flying over a futuristic city at sunset"
}

带可选参数的示例

{
  "model": "your-model-id",
  "prompt": "A bee flying over a futuristic city at sunset, wide cinematic shot, slow forward camera movement",
  "seconds": "5",
  "size": "1280x720"
}

curl --silent --show-error \
  --request POST 'https://routerbee.com/v1/videos' \
  --header "Authorization: Bearer $ROUTERBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "your-model-id",
    "prompt": "A bee flying over a futuristic city at sunset, wide cinematic shot, slow forward camera movement",
    "seconds": "5",
    "size": "1280x720"
  }'

创建请求字段

稳定字段

字段	类型	必填	默认行为	说明
model	string	是	无	必须使用 /v1/models 返回的完整模型 ID；示例中的 your-model-id 是占位符
prompt	string	是	无	非空文本，最长 10,000 个字符；描述主体、动作、场景、镜头和风格
seconds	string	否	模型默认值	部分模型的时长参数；使用详情页支持的值，只发送 seconds 或 duration 其中一个
size	string	否	模型默认值	部分模型的尺寸参数；使用详情页支持的格式和尺寸
input_reference	string	否	无	部分模型支持的参考图 HTTPS URL 或素材标识
metadata	object	否	{}	高级扩展参数；仅使用 RouterBee 或模型页面明确说明的键

兼容字段与别名

字段	类型	与哪个字段等价	使用限制
duration	integer 或整数字符串	seconds	不要和 seconds 同时发送；推荐使用 seconds
image	string	input_reference	不要和 input_reference 同时发送；推荐使用 input_reference
width	integer	size 的宽度	必须和 height 一起使用；推荐使用 size
height	integer	size 的高度	必须和 width 一起使用；推荐使用 size
mode	string	生成模式提示	通常由是否存在参考图自动判断，不建议手动设置
images	string[]	多参考图兼容字段	只有模型页面明确支持多图时才使用

不要发送冲突字段

不要同时发送 seconds 和 duration，也不要同时发送 size 与 width/height。冲突值可能导致生成参数和计费参数不一致。

model

先在模型广场查看模型详情，再调用 GET /v1/models 确认当前密钥的权限。把 data[].id 原样填入。不要自行删除版本号、修改大小写或添加供应商前缀。示例中的 your-model-id 不是可调用的真实模型。

prompt

推荐按以下顺序组织：

主体与环境 → 动作与变化 → 景别与构图 → 镜头运动 → 光线与风格 → 需要避免的问题

示例：

A woman waits on a rain-soaked station platform at night. She turns as a train approaches. Medium shot, slow dolly in, blue neon reflections, restrained cinematic lighting, stable facial features.

seconds / duration

• 值必须是正整数。
• 如模型详情页使用 seconds，可发送字符串形式，例如 "5"。
• 实际可用时长由模型决定；超出模型能力会返回 400 或上游拒绝。
• 时长可能参与计费，修改前请查看该模型详情页的价格。

size

使用 size 的模型通常要求 WIDTHxHEIGHT 格式：

1280x720
720x1280
720x720

• 使用小写 x，不能使用乘号 ×。
• 不要写成 720p、16:9 或 1280*720。
• 1280x720 表示横屏 16:9；720x1280 表示竖屏 9:16。
• 接口只校验格式不代表模型支持任意尺寸；有些模型使用其他尺寸字段。以模型详情页为准。

input_reference

图生视频示例：

{
  "model": "your-model-id",
  "prompt": "The camera slowly moves closer while the subject turns toward the window",
  "input_reference": "https://cdn.example.com/reference.jpg",
  "seconds": "5",
  "size": "1280x720"
}

参考图应当：

• 使用 RouterBee 服务端可以访问的 HTTPS 地址。
• 返回真实图片内容，而不是需要登录的网页。
• 在任务创建和上游读取期间保持有效。
• 不要把私有凭证放在 URL 查询参数中。

metadata

metadata 用于模型或供应商扩展参数。它必须是 JSON 对象：

{
  "metadata": {
    "negative_prompt": "flicker, unstable face"
  }
}

除非所选模型的详情页明确列出某个键，否则不要假定它会生效。模型专属参数应按详情页的示例放置，不能一概放入 metadata。

创建响应

{
  "id": "task_01abc...",
  "task_id": "task_01abc...",
  "object": "video",
  "model": "your-model-id",
  "status": "queued",
  "progress": 0,
  "created_at": 1787126400,
  "seconds": "5",
  "size": "1280x720"
}

字段	类型	一定存在	说明
id	string	是	公开任务 ID
task_id	string	通常	id 的兼容别名；客户端应优先读取 task_id ?? id
object	string	是	通常为 video
model	string	是	实际提交的公开模型名称
status	string	是	创建后通常为 queued 或 in_progress
progress	integer	是	0–100 的任务进度；只能用于展示，不应估算精确剩余时间
created_at	integer	是	Unix 秒级时间戳
seconds	string	否	接口确认的时长
size	string	否	接口确认的尺寸
error	object	否	任务失败时的错误信息

收到成功响应后，应立即持久化 task_id。不要只保存在进程内存中。

查询视频任务

GET https://routerbee.com/v1/videos/{task_id}
Authorization: Bearer $ROUTERBEE_API_KEY

该接口没有请求体，也没有查询参数。

curl --silent --show-error \
  "https://routerbee.com/v1/videos/$TASK_ID" \
  --header "Authorization: Bearer $ROUTERBEE_API_KEY"

状态值

status	是否终态	客户端行为
queued	否	3–5 秒后继续查询
in_progress	否	3–5 秒后继续查询
completed	是	调用内容接口下载视频
failed	是	停止轮询并记录 error 和请求 ID

推荐只按这四个公开状态编写新客户端。兼容旧客户端时，可以把 running 视为 in_progress、把 succeeded 视为 completed。

完成响应

{
  "id": "task_01abc...",
  "task_id": "task_01abc...",
  "object": "video",
  "model": "your-model-id",
  "status": "completed",
  "progress": 100,
  "created_at": 1787126400,
  "completed_at": 1787126495,
  "seconds": "5",
  "size": "1280x720"
}

完成响应不一定包含 video_url

/v1/videos/{task_id} 用于读取状态。任务完成后，请使用 /v1/videos/{task_id}/content 获取视频，不要依赖 result.video_url、video_url 或 data[0].url。

失败响应

{
  "id": "task_01abc...",
  "task_id": "task_01abc...",
  "object": "video",
  "model": "your-model-id",
  "status": "failed",
  "progress": 40,
  "error": {
    "code": "upstream_rejected",
    "message": "Provider rejected the task."
  }
}

下载视频内容

任务状态变成 completed 后调用：

GET https://routerbee.com/v1/videos/{task_id}/content
Authorization: Bearer $ROUTERBEE_API_KEY

该接口返回视频二进制流，不返回 JSON。

curl --fail --show-error --location \
  "https://routerbee.com/v1/videos/$TASK_ID/content" \
  --header "Authorization: Bearer $ROUTERBEE_API_KEY" \
  --output routerbee-video.mp4

成功时常见响应头：

HTTP/2 200
Content-Type: video/mp4
Content-Length: ...

下载时请注意：

• 必须继续携带 API Key。
• 未完成任务会返回 JSON 错误，不能当作 MP4 保存。
• 先检查 HTTP 状态和 Content-Type，再把响应写入文件。
• 大文件下载应使用流式写入，不要一次性读入内存。

轮询建议

1. 创建成功后保存任务 ID。
2. 等待约 3 秒再开始查询。
3. 每 3–5 秒查询一次，并逐步增加间隔。
4. 设置客户端总等待上限，例如 10 分钟。
5. 超过本地等待上限后停止轮询，但不要自动重新创建任务；稍后仍可用同一任务 ID 查询。

旧版兼容入口

RouterBee 仍可能兼容 /v1/video/generations，但其状态名称和响应外层结构与 /v1/videos 不同。新接入统一使用 /v1/videos，不要在同一个客户端中混用两套格式。

下一步

• 完整 cURL 与 Python 示例
• 错误码与排查
• 计费说明