开发文档

快速开始

云帧提供 REST API，让你把视频生成能力接入自有系统。三步跑通第一条视频：

1. 获取 API Key —— 在 管理后台 → API Key 管理 中创建密钥，请求时通过 Authorization: Bearer <key> 携带。
2. 提交生成任务 —— POST /api/v1/video/generate，返回任务信息（含任务 ID）。
3. 轮询任务状态 —— GET /api/v1/video/status?taskId=<id>，状态变为完成时取视频地址。

所有接口返回统一结构：{ "code": 0, "message": "ok", "data": { ... } }，code 非 0 表示出错，message 为错误原因。

三种生成方式

由请求体字段决定走哪条链路：

• 文生视频 (T2V) —— 只传 prompt。
• 图生视频 (I2V) —— 传 firstFrameImage（首帧），可选 lastFrameImage（尾帧）做分镜衔接。
• 多图参考 —— 传 images 数组提供多张参考图。

生成视频

POST /api/v1/video/generate

请求头：Authorization: Bearer <API_KEY>、Content-Type: application/json

请求体字段：

• prompt 必填 —— 文本提示词，最长 10000 字符。
• model —— 模型名，默认 doubao-seedance-2-0。
• resolution —— 480p / 720p / 1080p / 2k / 4k，默认 720p。
• duration —— 视频时长（秒），范围 1–30，默认 5。
• firstFrameImage / lastFrameImage —— 图生视频的首帧 / 尾帧图片地址。
• images —— 多张参考图地址数组。

请求示例：

POST /api/v1/video/generate
Authorization: Bearer sk-xxxxxxxx
Content-Type: application/json

{
  "prompt": "赛博朋克城市夜景，霓虹灯，电影运镜",
  "model": "doubao-seedance-2-0",
  "resolution": "1080p",
  "duration": 5
}

响应示例：

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "task_abc123",
    "status": "pending"
  }
}

查询任务

GET /api/v1/video/status?taskId=<taskId>

请求头：Authorization: Bearer <API_KEY>

轮询该接口直到 status 为完成状态，再从 data 取视频地址。任务不属于当前密钥所有者时返回错误。

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "task_abc123",
    "status": "completed",
    "videoUrl": "https://cdn.../video.mp4"
  }
}

视频 CDN 地址有时效，请及时转存或下载。

计费说明

充值比例 1 元 = 100 积分。每次生成按「时长 × 分辨率对应单价」预扣积分，积分不足会返回错误。具体单价由管理员在 后台 → 定价管理 中按 渠道 × 模型 × 分辨率 配置。

广告创意工作流

面向广告主的推荐用法 —— 把一个卖点变成一整批可投放素材：

1. 扩写脚本 —— 用文本能力把卖点扩成多版分镜与文案。
2. 批量提交 —— 对每个脚本 × 每个画面比例各调一次 /api/v1/video/generate。
3. 轮询整批 —— 用 /api/v1/video/status 跟踪每个任务状态。
4. 导出投放 —— 取视频地址，按比例分发到各投放渠道测试。

需要可视化操作？直接进 工作台 体验，无需写代码。