SD2.0 视频生成

SD2.0 视频接口支持文生视频和图生视频，采用异步任务流程：提交任务、轮询状态、下载 MP4。

模型与画幅

常见模型标识如下，实际可用性以 /v1/models 为准：

模型	目标时长	支持画幅
video-v1-5s	5 秒	16:9、9:16、1:1
video-v1-10s	10 秒	16:9、9:16、1:1
video-v1-15s	15 秒	16:9、9:16、1:1

1. 提交任务

POST https://api.topapis.cn/v1/video/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

参数	类型	必填	说明
model	string	是	当前账号可用的视频模型标识
prompt	string	是	画面、动作和镜头描述
image	string	否	单张参考图 URL 或带 MIME 前缀的 Base64 data URI
images	string[]	否	参考图数组，与 image 二选一
ratio	string	否	默认 16:9；也可使用 9:16 或 1:1

只传 prompt 为文生视频；加入 image 或 images 为图生视频。

curl "https://api.topapis.cn/v1/video/generations" \
  -H "Authorization: Bearer $TOPAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-v1-5s",
    "prompt": "晨光中的城市街道，镜头平稳向前移动",
    "ratio": "16:9"
  }'

图生视频可加入首帧：

{
  "model": "video-v1-5s",
  "prompt": "镜头缓慢推进，主体轻轻转头",
  "image": "https://example.com/first-frame.jpg",
  "ratio": "16:9"
}

Base64 必须带 data:image/jpeg;base64, 或 data:image/png;base64, 前缀。远程图片必须允许服务器直接访问。

提交成功后保存任务 ID：

{
  "task_id": "task_example",
  "status": "queued",
  "seconds": "5"
}

2. 轮询状态

GET https://api.topapis.cn/v1/video/generations/{task_id}
Authorization: Bearer YOUR_API_KEY

建议约每 15 秒查询一次，不要高频轮询。

状态	含义	操作
queued	等待处理	继续等待
IN_PROGRESS	正在生成	继续轮询
SUCCESS	任务完成	下载视频
FAILURE	任务失败	记录错误，稍后决定是否重新提交

成功响应可能包含相对下载地址：

{
  "task_id": "task_example",
  "status": "SUCCESS",
  "result_url": "/v1/videos/task_example/content"
}

3. 下载视频

GET https://api.topapis.cn/v1/videos/{task_id}/content
Authorization: Bearer YOUR_API_KEY

下载完成后验证 HTTP 状态、Content-Type 和文件大小，再保存 MP4。

任务管理

• 视频生成可能持续数分钟，轮询进度暂时不变不等于失败。
• 保存 task_id，应用重启后继续查询同一任务。
• 提交超时不代表服务器未接收任务，避免立即重复扣费。
• 图生视频失败时先检查图片 URL 的公网可访问性和 Base64 前缀。