视频生成

Router 为视频生成模型提供统一的异步任务接口。一次视频请求分为三步：创建任务 → 轮询任务状态 → 下载结果。视频模型与文本模型使用同一个 API Key、同一套额度与调用记录。

当前支持火山方舟 Doubao-Seedance 系列（由运营在控制台接入）。视频模型在「可用模型」列表中的 modality 为 video；分辨率、时长、比例等参数以模型实际支持为准。

接入地址

以控制台「快速接入」页展示的域名为准：

风格	Base URL	端点
OpenAI Videos	https://routerapi.<域名>/v1	POST /v1/videos、GET /v1/videos/{id}、GET /v1/videos/{id}/content、DELETE /v1/videos/{id}
New API 任务风格	https://routerapi.<域名>/v1	POST /v1/video/generations、GET /v1/video/generations/{id}

两个面共享同一个任务：在任一面创建，都可以用同一个任务 ID 在另一面查询或下载，只计费一次。

鉴权：Authorization: Bearer <Key>（视频面也兼容 x-api-key）。

OpenAI Videos 风格

创建任务

curl -X POST https://routerapi.<域名>/v1/videos \
  -H "Authorization: Bearer $VEYRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-5-pro",
    "prompt": "雨后的霓虹街道，镜头缓慢推进",
    "seconds": 5,
    "size": "1280x720",
    "input_reference": "https://cdn.example.com/first-frame.jpg",
    "provider": {
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "generate_audio": false,
      "seed": 42
    }
  }'

创建成功返回 202：

{
  "id": "vid_01J8...",
  "object": "video",
  "model": "seedance-1-5-pro",
  "status": "queued",
  "progress": 0,
  "created_at": 1762396800,
  "completed_at": null,
  "expires_at": null,
  "error": null
}

请求字段：

字段	说明
model	必填，视频模型名
prompt	必填，视频描述
seconds	时长（秒）；不传按模型默认值
size	尺寸，宽x高；也可用 provider.resolution / provider.aspect_ratio
input_reference	首帧图片地址（URL 或 data URI）
provider	视频参数：resolution、aspect_ratio、generate_audio、seed、watermark、last_frame、content 等

也支持 multipart/form-data，用 input_reference 文件字段上传首帧（单文件建议不超过 10MB）。

查询任务

curl https://routerapi.<域名>/v1/videos/vid_01J8... \
  -H "Authorization: Bearer $VEYRA_API_KEY"

成功终态示例：

{
  "id": "vid_01J8...",
  "object": "video",
  "model": "seedance-1-5-pro",
  "status": "completed",
  "progress": 100,
  "created_at": 1762396800,
  "completed_at": 1762396905,
  "seconds": 5,
  "size": "1280x720",
  "usage": {
    "video_tokens": 50638,
    "duration_seconds": 5,
    "resolution": "720p",
    "audio": false
  },
  "content_url": "/v1/videos/vid_01J8.../content",
  "expires_at": 1762483300,
  "error": null
}

状态映射：queued（排队中）、in_progress（生成中）、completed（完成）、failed（失败）。取消或过期的任务在 OpenAI 面也显示为 failed，error.code 分别为 video_cancelled / video_expired。

下载视频

curl -L https://routerapi.<域名>/v1/videos/vid_01J8.../content \
  -H "Authorization: Bearer $VEYRA_API_KEY" \
  -o video.mp4

下载地址支持 Range 断点续传。视频产物 URL 由上游签名，通常约 24 小时有效；过期后下载接口会尝试刷新一次，仍不可用则返回 410 video_expired，请及时保存结果。

取消任务

curl -X DELETE https://routerapi.<域名>/v1/videos/vid_01J8... \
  -H "Authorization: Bearer $VEYRA_API_KEY"

当前上游不支持取消时返回 409 cancel_not_supported；任务已完成时返回 409 video_not_cancellable。

New API 任务风格

创建任务

curl -X POST https://routerapi.<域名>/v1/video/generations \
  -H "Authorization: Bearer $VEYRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-1-5-pro",
    "prompt": "雨后的霓虹街道，镜头缓慢推进",
    "image": "https://cdn.example.com/first-frame.jpg",
    "duration": 5,
    "width": 1280,
    "height": 720,
    "fps": 24,
    "metadata": {
      "generate_audio": false,
      "resolution": "720p",
      "aspect_ratio": "16:9",
      "last_frame": "https://cdn.example.com/last-frame.jpg"
    }
  }'

响应：

{
  "id": "vid_01J8...",
  "object": "video",
  "task_id": "vid_01J8...",
  "model": "seedance-1-5-pro",
  "status": "queued",
  "created_at": 1762396800
}

查询任务

curl https://routerapi.<域名>/v1/video/generations/vid_01J8... \
  -H "Authorization: Bearer $VEYRA_API_KEY"

{
  "task_id": "vid_01J8...",
  "status": "succeeded",
  "url": "/v1/videos/vid_01J8.../content",
  "format": "mp4",
  "metadata": {"duration_seconds": 5, "resolution": "720p", "audio": false},
  "error": null
}

New API 面的状态为 queued / in_progress / succeeded / failed / cancelled / expired。

幂等与轮询

• 创建任务可带 Idempotency-Key 请求头（或请求体 client_request_id）。同一个 Key 在 24 小时内重复提交相同请求会返回同一任务；请求体不同返回 409 idempotency_conflict。
• 建议轮询间隔 5–10 秒；同一任务 2 秒内的重复查询会返回 429 video_poll_rate_limited 与 Retry-After。
• 同一 API Key 同时进行中的任务数有上限，达到上限返回 429 video_concurrency_limited。

计费

视频按模型配置的计量单位计费，常见为：

• 按秒：时长 × 每秒单价
• 按条：每次任务固定价
• 按 Token：按上游返回的生成 token 数计价

价格可能按分辨率、有声/静音等变体不同。调用方只看最终售价；未定价的视频模型不会出现在目录中，也无法创建任务。任务创建后按完成时生效的价格计费；失败、取消、过期的任务不产生费用。

若账户剩余可用预算不足以覆盖该任务的最高费用预估，创建会被直接拒绝（429 budget_exceeded），避免异步任务在完成时才暴露大额超支。

费用和用量可在控制台「我的视频任务」或任务详情中查看。

错误码

HTTP	错误码	说明
400	invalid_request	参数缺失或格式错误
401	invalid_api_key	API Key 无效
403	model_not_allowed / 额度或空间限制	当前 Key 无权调用该模型
404	video_not_found	任务不存在或不属于当前 Key
409	idempotency_conflict / cancel_not_supported	幂等冲突 / 当前模型不支持取消
410	video_expired	视频下载地址已过期
429	video_concurrency_limited	并发任务已满，请稍后重试
429	video_poll_rate_limited	轮询过于频繁，请按 Retry-After 间隔后再查
429	budget_exceeded	可用预算不足以创建该任务，请充值或调整规格
502	video_upstream_error	视频服务暂时不可用

常见问题

• 为什么不能一次性拿到视频？ 视频生成耗时较长，接口采用异步任务模型，创建后通过轮询获取结果。
• 下载链接能保存多久？ 上游签名链接通常约 24 小时有效，请生成后及时下载或转存。
• 任务完成后还能取消吗？ 不能。取消仅对进行中的任务生效。
• 两个接口风格能混用吗？ 能。任务 ID 在两个面通用，任一面创建都可在另一面查询。