RouterBee API Key 使用教程：从创建密钥到获取视频

本教程面向第一次使用 RouterBee API 的用户，介绍如何创建 API Key、提交视频生成任务、查询任务状态并取得最终视频地址。

API 地址说明

用途	地址
RouterBee 网站/API 域名	`https://routerbee.com`
OpenAI 兼容 Base URL（用于 SDK）	`https://routerbee.com/v1`
创建视频完整接口	`https://routerbee.com/v1/videos`
查询任务完整接口	`https://routerbee.com/v1/videos/{task_id}`

使用 cURL 时，请填写完整接口地址。使用支持自定义 OpenAI Base URL 的 SDK 时，请将 base_url 设置为 https://routerbee.com/v1，不要重复拼接 /v1。

使用流程

mermaid

flowchart LR
    A[创建 API Key] --> B[POST /v1/videos 提交任务]
    B --> C[保存 task_id]
    C --> D[GET /v1/videos/task_id 查询状态]
    D -->|尚未完成| D
    D -->|completed| E[读取 video_url]
    D -->|failed| F[查看 error 和 request_id]

1. 创建 API Key

登录 RouterBee。
进入“控制台 → API 密钥”，或直接打开 API 密钥页面。
点击“创建 API 密钥”。
填写一个容易识别的名称，例如 video-production。
根据需要设置分组、有效期和额度；没有特殊要求时使用 default 分组。
创建后立即复制并安全保存 API Key。

API Key 通常以 sk- 开头。密钥相当于账户密码：

不要发送到聊天群、工单或公开仓库。
不要写在网页前端或移动 App 中。
不要提交到 Git；生产环境应使用环境变量或密钥管理服务。
如果密钥疑似泄露，请立即在控制台禁用或删除，然后创建新密钥。

2. 保存 API Key

在 macOS 或 Linux 终端中，可以临时保存为环境变量：

bash

export ROUTERBEE_API_KEY='替换为你的_API_KEY'

确认变量已经设置，但不要把完整密钥打印到终端日志：

bash

test -n "$ROUTERBEE_API_KEY" && echo "API Key 已设置"

3. 选择模型

RouterBee 当前提供以下对外模型名称：

模型	适用场景
`seedance-2.5`	最新版本视频生成
`seedance-2.0`	高质量多模态视频生成
`seedance-2.0-fast`	更快的生成速度与较低价格
`seedance-2.0-mini`	高性价比视频生成

请求时只需填写上表中的 RouterBee 模型名称，不需要填写供应商内部模型 ID。

4. 提交视频生成任务

下面的请求会生成一段 5 秒、720p、16:9 的视频：

bash

curl --request POST 'https://routerbee.com/v1/videos' \
  --header "Authorization: Bearer $ROUTERBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: video-demo-001' \
  --data '{
    "model": "seedance-2.0-fast",
    "prompt": "A bee flying over a futuristic city at sunset, cinematic lighting",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5
    }
  }'

请求参数

参数	必填	说明
`model`	是	RouterBee 对外模型名称
`prompt`	是	视频画面、动作、镜头和风格描述
`seconds`	建议	视频时长，示例使用字符串 `"5"`
`metadata.resolution`	建议	例如 `480p`、`720p`；可用范围取决于模型
`metadata.ratio`	建议	例如 `16:9`、`9:16`、`1:1`
`metadata.duration`	建议	与 `seconds` 保持一致的数字

seedance-2.0-fast 和 seedance-2.0-mini 建议使用 480p 或 720p。不同模型支持的分辨率可能不同，请以模型广场和最新文档为准。

为什么要设置 Idempotency-Key

Idempotency-Key 用于防止网络重试时意外创建两个相同任务：

同一个 Key 配合同一个请求体重复提交，应返回同一个任务。
每个真正的新视频都应使用新的 Key。
不要用同一个 Key 提交不同的请求体，否则可能返回冲突错误。

在脚本中可以生成一个新值：

bash

IDEMPOTENCY_KEY="video-$(date +%s)-$RANDOM"

5. 读取创建结果

创建成功后会返回 JSON。字段可能随兼容模式略有增加，核心字段如下：

json

{
  "id": "rbjob_示例任务ID",
  "task_id": "rbjob_示例任务ID",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "seconds": "5"
}

请保存 task_id。如果响应只提供 id，也可以将 id 作为任务 ID：

bash

CREATE_RESPONSE=$(curl --silent --show-error \
  --request POST 'https://routerbee.com/v1/videos' \
  --header "Authorization: Bearer $ROUTERBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "model": "seedance-2.0-fast",
    "prompt": "A bee flying over a futuristic city at sunset, cinematic lighting",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5
    }
  }')

TASK_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.task_id // .id // empty')

if [ -z "$TASK_ID" ]; then
  echo "任务创建失败：$CREATE_RESPONSE"
  exit 1
fi

echo "任务已创建：$TASK_ID"

上述示例使用 jq 解析 JSON。如果本机没有 jq，也可以直接查看原始响应并复制 task_id。

6. 查询任务状态

视频生成是异步任务。拿到任务 ID 后，请通过以下接口查询：

bash

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

常见状态：

状态	含义	应采取的操作
`queued`	任务排队中	稍后继续查询
`in_progress` / `running`	正在生成	稍后继续查询
`completed` / `succeeded`	生成成功	读取视频地址
`failed` / `cancelled`	任务失败或取消	查看 `error` 字段

建议每 3 至 5 秒查询一次，不要高频轮询。

7. 获取最终视频地址

成功响应的核心结构如下；不同兼容模式可能将视频地址放在 result.video_url 或 video_url：

json

{
  "id": "rbjob_示例任务ID",
  "task_id": "rbjob_示例任务ID",
  "status": "completed",
  "progress": 100,
  "result": {
    "video_url": "https://视频下载地址/example.mp4"
  }
}

可以兼容读取几个常见位置：

bash

VIDEO_URL=$(printf '%s' "$TASK_RESPONSE" | \
  jq -r '.result.video_url // .video_url // .data[0].url // empty')

视频地址可能具有有效期。取得地址后，请及时下载并保存到自己的存储空间。

8. 完整 cURL 轮询示例

以下脚本完成“提交任务 → 等待 → 输出视频地址”的全过程：

bash

#!/usr/bin/env bash
set -euo pipefail

: "${ROUTERBEE_API_KEY:?请先设置 ROUTERBEE_API_KEY}"

IDEMPOTENCY_KEY="video-$(date +%s)-$RANDOM"

CREATE_RESPONSE=$(curl --silent --show-error \
  --request POST 'https://routerbee.com/v1/videos' \
  --header "Authorization: Bearer $ROUTERBEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "model": "seedance-2.0-fast",
    "prompt": "A bee flying over a futuristic city at sunset, cinematic lighting",
    "seconds": "5",
    "metadata": {
      "resolution": "720p",
      "ratio": "16:9",
      "duration": 5
    }
  }')

TASK_ID=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.task_id // .id // empty')

if [ -z "$TASK_ID" ]; then
  echo "任务创建失败：$CREATE_RESPONSE" >&2
  exit 1
fi

echo "任务已创建：$TASK_ID"

while true; do
  TASK_RESPONSE=$(curl --silent --show-error \
    "https://routerbee.com/v1/videos/$TASK_ID" \
    --header "Authorization: Bearer $ROUTERBEE_API_KEY")

  STATUS=$(printf '%s' "$TASK_RESPONSE" | jq -r '.status // empty')
  PROGRESS=$(printf '%s' "$TASK_RESPONSE" | jq -r '.progress // 0')
  echo "状态：$STATUS，进度：$PROGRESS%"

  case "$STATUS" in
    completed|succeeded)
      VIDEO_URL=$(printf '%s' "$TASK_RESPONSE" | \
        jq -r '.result.video_url // .video_url // .data[0].url // empty')

      if [ -z "$VIDEO_URL" ]; then
        echo "任务已成功，但响应中没有找到视频地址：$TASK_RESPONSE" >&2
        exit 1
      fi

      echo "视频地址：$VIDEO_URL"
      break
      ;;
    failed|cancelled)
      echo "任务失败：$TASK_RESPONSE" >&2
      exit 1
      ;;
    queued|in_progress|running)
      sleep 5
      ;;
    *)
      echo "未知状态：$TASK_RESPONSE" >&2
      exit 1
      ;;
  esac
done

9. Python 完整示例

安装依赖：

bash

pip install requests

创建 routerbee_video.py：

python

import os
import time
import uuid

import requests


# 这里保存的是站点域名；下面的 requests 调用会自行拼接 /v1/videos。
# 如果某个 OpenAI 兼容 SDK 要求填写 base_url，请改用 https://routerbee.com/v1。
API_ORIGIN = "https://routerbee.com"
API_KEY = os.environ["ROUTERBEE_API_KEY"]

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "Idempotency-Key": f"video-{uuid.uuid4()}",
}

payload = {
    "model": "seedance-2.0-fast",
    "prompt": "A bee flying over a futuristic city at sunset, cinematic lighting",
    "seconds": "5",
    "metadata": {
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
}

create_response = requests.post(
    f"{API_ORIGIN}/v1/videos",
    headers=headers,
    json=payload,
    timeout=60,
)
create_response.raise_for_status()
created = create_response.json()

task_id = created.get("task_id") or created.get("id")
if not task_id:
    raise RuntimeError(f"响应中没有任务 ID：{created}")

print(f"任务已创建：{task_id}")

query_headers = {"Authorization": f"Bearer {API_KEY}"}

while True:
    task_response = requests.get(
        f"{API_ORIGIN}/v1/videos/{task_id}",
        headers=query_headers,
        timeout=30,
    )
    task_response.raise_for_status()
    task = task_response.json()

    status = task.get("status")
    progress = task.get("progress", 0)
    print(f"状态：{status}，进度：{progress}%")

    if status in {"completed", "succeeded"}:
        result = task.get("result") or {}
        data = task.get("data") or []
        video_url = (
            result.get("video_url")
            or task.get("video_url")
            or (data[0].get("url") if data else None)
        )
        if not video_url:
            raise RuntimeError(f"任务成功，但响应中没有视频地址：{task}")
        print(f"视频地址：{video_url}")
        break

    if status in {"failed", "cancelled"}:
        raise RuntimeError(f"视频生成失败：{task}")

    if status not in {"queued", "in_progress", "running"}:
        raise RuntimeError(f"未知任务状态：{task}")

    time.sleep(5)

运行：

bash

python routerbee_video.py

10. 常见错误

`401 Unauthorized`

原因通常是 API Key 缺失、错误、被禁用或已过期。确认请求头格式为：

http

Authorization: Bearer sk-你的密钥

`400 invalid_request`

检查以下内容：

model 是否为 RouterBee 模型广场中的有效名称。
prompt 是否为空。
seconds、分辨率和比例是否受所选模型支持。
请求体是否为合法 JSON。

`402` 或余额不足

进入 RouterBee 钱包充值或兑换额度，然后重新提交一个使用新 Idempotency-Key 的任务。

`409 idempotency_conflict`

同一个 Idempotency-Key 被用于不同请求。生成一个新 Key 后再次提交。

`429 Too Many Requests`

请求或查询过于频繁。降低请求速度，并使用指数退避重试。

`5xx` 或上游暂时不可用

记录响应中的 request_id，稍后重试。创建任务重试时应继续使用原来的 Idempotency-Key，避免创建重复任务。

11. 计费与安全建议

创建视频任务可能产生费用；查询任务状态不会重复创建视频。
不要因为等待时间较长而重复发送 POST /v1/videos。
网络超时时，先用相同的 Idempotency-Key 重试原请求。
为开发、测试和生产环境分别创建 API Key，并设置合理额度。
定期检查“使用日志”和“任务日志”。
服务端日志应过滤 Authorization 请求头，避免记录完整 API Key。

快速检查清单

[ ] 已在 RouterBee 控制台创建 API Key
[ ] API Key 已保存在服务端环境变量中
[ ] 请求使用 Authorization: Bearer ...
[ ] 每个新视频使用唯一 Idempotency-Key
[ ] 已保存创建响应中的 task_id 或 id
[ ] 使用 GET /v1/videos/{task_id} 查询任务
[ ] 成功后已读取并及时保存 video_url

RouterBee API Key 使用教程：从创建密钥到获取视频 ​

API 地址说明 ​

使用流程 ​

1. 创建 API Key ​

2. 保存 API Key ​

3. 选择模型 ​

4. 提交视频生成任务 ​

请求参数 ​

为什么要设置 Idempotency-Key ​

5. 读取创建结果 ​

6. 查询任务状态 ​

7. 获取最终视频地址 ​

8. 完整 cURL 轮询示例 ​

9. Python 完整示例 ​

10. 常见错误 ​

401 Unauthorized ​

400 invalid_request ​

402 或余额不足 ​

409 idempotency_conflict ​

429 Too Many Requests ​

5xx 或上游暂时不可用 ​

11. 计费与安全建议 ​

快速检查清单 ​

RouterBee API Key 使用教程：从创建密钥到获取视频

API 地址说明

使用流程

1. 创建 API Key

2. 保存 API Key

3. 选择模型

4. 提交视频生成任务

请求参数

为什么要设置 Idempotency-Key

5. 读取创建结果

6. 查询任务状态

7. 获取最终视频地址

8. 完整 cURL 轮询示例

9. Python 完整示例

10. 常见错误

`401 Unauthorized`

`400 invalid_request`

`402` 或余额不足

`409 idempotency_conflict`

`429 Too Many Requests`

`5xx` 或上游暂时不可用

11. 计费与安全建议

快速检查清单