API 文档

通过 REST API 接入 Seedance 视频生成能力，快速集成到您的应用中。

快速开始

注册账号并登录，前往 API Key 管理获取您的 API Key

调用 GET /api/v1/models 获取可用模型列表

调用 POST /api/v1/video/generate 提交生成任务

轮询 GET /api/v1/video/tasks/:id 查询状态，或配置 webhook 接收回调

鉴权方式

所有 API 请求需要在 Header 中携带 API Key 进行鉴权：

Authorization: Bearer bc_xxxxxxxxxxxxxxxx

API Key 以 bc_ 开头。请在用户控制台 → API Key 管理中创建和管理。请妥善保管，不要泄露到客户端代码中。

计费方式

采用预扣费模式，生成前扣除预估费用，生成失败自动全额退款。

按时长计费模型：

费用 = 每秒定价 × 时长 × 分辨率倍率 + 音频附加费 + 素材加价

按次计费模型：

费用 = 每次价格 × 画质倍率

按次计费模型通常固定时长和分辨率，仅支持图片参考。

具体价格请参考价格页或模型列表接口。

接口列表

POST

提交视频生成任务

/api/v1/video/generate

提交一个视频生成任务，返回任务ID用于后续查询状态。支持 model 或 model_id 参数，二选一即可。

请求参数

参数名	类型	必填	说明
model / model_id	string	是	模型标识（二选一）。model 传名称如 seedance-2.0；model_id 传 UUID
prompt	string	是	视频生成提示词，长度 1-20480
resolution	string	否	分辨率：480p / 720p / 1080p / 2k，默认 720p。按次计费模型可能限制可选分辨率
duration	number	否	视频时长（秒）：5-15，默认 15。按次计费模型固定时长
ratio	string	否	宽高比：16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9，默认 16:9
generate_audio	boolean	否	是否生成音频，默认 false。按次计费模型不支持
image_urls	string[]	否	参考图片 URL 列表，最多 9 张
video_urls	string[]	否	参考视频 URL 列表，最多 3 个。按次计费模型不支持
audio_urls	string[]	否	参考音频 URL 列表，最多 3 段。按次计费模型不支持
seed	number	否	随机种子，-1 表示随机
webhook_url	string	否	任务完成回调 URL，POST 请求

请求示例

curl -X POST https://your-domain.com/api/v1/video/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bc_xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "一只可爱的橘猫在阳光下打盹，微风轻拂它的毛发",
    "resolution": "720p",
    "duration": 15,
    "ratio": "16:9",
    "generate_audio": false,
    "image_urls": ["https://example.com/image.jpg"],
    "seed": -1,
    "webhook_url": "https://your-domain.com/webhook"
  }'

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "3c09b361-2b1a-4888-86a7-7667dc0349ef",
    "status": "pending",
    "cost": 18.00,
    "created_at": "2026-01-24T10:00:00.000Z"
  }
}

GET

查询任务状态

/api/v1/video/tasks/:id

根据任务ID查询生成进度和结果。进行中的任务会主动向上游同步最新状态。视频生成成功后需转存到永久存储，转存期间状态为 transferring。

响应字段

参数名	类型	说明
task_id	string	任务唯一标识（UUID）
status	string	任务状态：pending / running / transferring / success / failed / refunded
video_url	string	七牛云签名视频 URL（转存完成后可用）。有效期 24 小时，过期后需重新查询获取新签名。转存中时为 null
cost	number	实际消耗费用（元），失败时自动退款
created_at	string	任务创建时间（ISO 8601）
finished_at	string	任务完成时间（ISO 8601），进行中为 null
error_message	string	错误信息（失败时有值）

请求示例

curl https://your-domain.com/api/v1/video/tasks/3c09b361-2b1a-4888-86a7-7667dc0349ef \
  -H "Authorization: Bearer bc_xxxxxxxxxxxxxxxx"

响应示例

// 转存中（视频生成成功，正在转存到永久存储）
{
  "code": 0,
  "message": "视频正在转存中，请稍后重新查询",
  "data": {
    "task_id": "3c09b361-2b1a-4888-86a7-7667dc0349ef",
    "status": "transferring",
    "video_url": null,
    "created_at": "2026-07-20T22:48:43.771Z",
    "finished_at": null,
    "cost": 18.00
  }
}

// 转存完成
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "3c09b361-2b1a-4888-86a7-7667dc0349ef",
    "status": "success",
    "video_url": "https://sd.duanjusns.cn/videos/xxx/xxx.mp4?e=xxx&token=xxx",
    "created_at": "2026-07-20T22:48:43.771Z",
    "finished_at": "2026-07-20T22:54:37.633Z",
    "cost": 18.00
  }
}

GET

查询账户余额

/api/v1/account/balance

查询当前 API Key 所属账户的可用余额。

响应字段

参数名	类型	说明
balance	number	可用余额（元）
currency	string	货币单位，固定为 CNY

请求示例

curl https://your-domain.com/api/v1/account/balance \
  -H "Authorization: Bearer bc_xxxxxxxxxxxxxxxx"

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "balance": 100.50,
    "currency": "CNY"
  }
}

GET

获取模型列表

/api/v1/models

获取所有可用模型及定价信息。

响应字段

参数名	类型	说明
id	string	模型标识，用于提交生成时的 model 参数
name	string	模型英文名称
display_name	string	模型展示名称
description	string	模型说明
status	string	状态：active / inactive
billing_mode	string	计费模式：per_second（按时长）/ per_call（按次）
pricing.price_per_call	number	按次计费时的每次价格
pricing.price_per_second	number	按时长计费时的每秒基础价格
pricing.resolution_multipliers	object	各分辨率倍率，0 表示不支持该分辨率
pricing.audio_extra	number	音频生成附加费

请求示例

curl https://your-domain.com/api/v1/models \
  -H "Authorization: Bearer bc_xxxxxxxxxxxxxxxx"

响应示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "seedance-2.0",
      "name": "seedance-2.0",
      "display_name": "Seedance 2.0 视频生成",
      "description": null,
      "status": "active",
      "billing_mode": "per_call",
      "pricing": {
        "price_per_call": 18.00,
        "price_per_second": 0,
        "resolution_multipliers": {
          "480p": 0,
          "720p": 1,
          "1080p": 0,
          "2k": 0
        },
        "audio_extra": 0
      }
    }
  ]
}

错误码

0成功

400参数错误（缺少必填参数或格式不合法）

401API Key 无效或已停用

402余额不足，请充值后再试

403无权访问该资源

404资源不存在

429请求过于频繁，请稍后重试

500服务器内部错误

任务状态

pending排队中- 任务已创建，等待处理

running生成中- 正在生成视频

transferring转存中- 视频生成成功，正在转存到永久存储

success已完成- 视频生成成功，可下载播放

failed失败- 生成失败，已自动退款

refunded已退款- 任务取消或失败，已退款

视频生成成功后会自动转存到七牛云永久存储，转存期间状态为 transferring，video_url 为 null。转存完成后状态变为 success，video_url 返回七牛云签名链接。签名 URL 有效期 24 小时，过期后重新查询即可获取新签名。上传素材 48 小时自动清除。

视频转存流程

视频生成成功后，会自动转存到七牛云永久存储。整个流程如下：

pending→ 任务已创建，等待处理

running→ 正在生成视频

transferring→ 视频生成成功，正在转存到永久存储（video_url 为 null）

success→ 转存完成，video_url 返回七牛云签名链接

轮询时遇到 transferring 状态，建议间隔 5-10 秒后重新查询。转存通常在数秒内完成。

Webhook 回调

在提交任务时传入 webhook_url 参数，任务转存完成后会向该地址发送 POST 请求：

{
  "task_id": "任务ID",
  "status": "success / failed",
  "video_url": "七牛云签名视频URL（成功时有，转存完成后才回调）",
  "error_message": "错误信息（失败时有）",
  "cost": 18.00,
  "finished_at": "完成时间"
}

Webhook 在视频转存完成后才触发，确保返回的 video_url 可直接使用。请确保您的 webhook 接口返回 2xx 状态码，否则可能会重试。建议配合轮询机制做双重保障。