Seedance 2.0 API 对接文档

版本：v1.1（平台版） | 更新日期：2026-06-29

说明：本文档面向 StoneRoll AI 平台（https://stonerollai.com）接入方，描述 Seedance 2.0 视频生成与素材库 API 的请求/响应参数。

一、通用说明

1.1 接入地址

项目	值
Base URL	`https://stonerollai.com`
视频生成 — 创建任务	`POST /v1/video/generations`
视频生成 — 查询任务	`GET /v1/video/generations/{task_id}`
素材库 — 统一入口	`POST /api/material?Action=<动作名>`
真人认证 H5 回调	`POST /api/rv?Action=<动作名>`
文档站点	`https://stonerollai.com/seedance-docs/`

视频生成为异步任务：创建 → 轮询查询 → 下载结果。

1.2 认证方式

所有接口使用 平台 Token 鉴权（在控制台 → 令牌管理创建）：

http

Authorization: Bearer sk-xxxxxxxxxxxxxxxx
Content-Type: application/json

素材库 /api/material、视频 /v1/video/generations 均使用同一 Token。
H5 真人认证回调 /api/rv 使用 rt_ 临时令牌，不使用 sk- Token（见 3.10）。
可选：绑定指定渠道时使用 sk-xxx-<channelId> 格式。

1.3 计费说明

接口	平台行为
视频生成	按 `completion_tokens` 扣除平台额度（预扣 → 成功结算 / 失败退还）
素材库 / 真人认证	不计费，不消耗额度、不写消费日志

1.4 接入补充

平台自动处理（无需客户端额外传参）：

图生视频：顶层 images[] 会自动补 role: reference_image。
metadata.content 中 video_url 无 role 时自动补 reference_video。

真人认证 H5： CreateRealValidateH5 返回的链接形如 https://stonerollai.com/rv?t=rt_xxx，可发给终端用户扫码；H5 页面通过 /api/rv 完成认证（不暴露 sk- Token）。

二、视频生成 API

2.1 接口概览

项目	说明
创建任务	`POST /v1/video/generations`
查询任务	`GET /v1/video/generations/{task_id}`
主力模型	`doubao-seedance-2-0-260128`（另支持 `doubao-seedance-2-0-fast-260128`、`doubao-seedance-1-5-pro-251215` 等 Seedance 系列）
交互模式	异步轮询：创建 → 轮询 → 下载

2.2 生成模式

模式	说明	请求写法
文生视频	纯文本描述生成视频	`prompt` + `metadata`
图生视频	图片 + 文本生成视频	`prompt` + `images[]` + `metadata`
视频生视频	参考视频 + 文本生成视频	`prompt` + `metadata.content` 中的 `video_url`
素材引用	引用素材库资产 + 文本生成视频	`prompt` + `metadata.content` 中的 `asset://`

2.3 创建任务 — 请求字段

POST /v1/video/generations

字段	类型	必填	说明
`model`	string	是	模型名称，如 `doubao-seedance-2-0-260128`
`prompt`	string	是	文本提示词
`images`	string[]	否	图生视频参考图，须为公网可访问 URL（`http`/`https`）
`image`	string	否	单图便捷写法，等价于 `images: [image]`
`seconds`	string	否	时长（秒），如 `"5"`；优先级高于 `metadata.duration`
`metadata`	object	否	扩展参数，见下表

metadata 支持字段：

字段	类型	说明
`resolution`	string	分辨率：`480p`（默认）、`720p`、`1080p`
`ratio`	string	宽高比：`16:9`（默认）、`9:16`、`3:4`、`1:1`、`4:3`
`duration`	integer	时长（秒），4~15，默认 5（顶层 `seconds` 存在时以 `seconds` 为准）
`watermark`	boolean	是否加水印，默认 false
`seed`	integer	随机种子
`camera_fixed`	boolean	是否固定镜头
`content`	array	视频生视频、素材引用等场景使用，结构见 2.3.1

metadata.content 中的 text 条目会被忽略，由顶层 prompt 覆盖；image_url / video_url 条目（含 role）会保留。

2.3.1 metadata.content 条目与 role

字段	类型	说明
`type`	string	`text` / `image_url` / `video_url`
`text`	string	`type=text` 时的提示词（会被顶层 `prompt` 覆盖，一般不必填）
`image_url`	object	`{ "url": "..." }`，可为公网 URL 或 `asset://{AssetID}`
`video_url`	object	`{ "url": "..." }`，参考视频公网 URL
`role`	string	媒体角色，见下表

`role`	配套 `type`	含义
`reference_image`	`image_url`	参考图；图生视频、素材引用必填
`reference_video`	`video_url`	参考视频；视频生视频必填

2.4 文生视频

json

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "一只金色柴犬在樱花树下奔跑，镜头缓缓上升",
  "seconds": "5",
  "metadata": {
    "resolution": "480p",
    "ratio": "16:9",
    "watermark": false
  }
}

2.5 图生视频

json

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "让画面中的人物缓缓转身微笑",
  "images": ["https://example.com/photo.jpg"],
  "seconds": "5",
  "metadata": {
    "resolution": "480p",
    "ratio": "16:9"
  }
}

图片须为公网可访问 URL；本地文件请先上传到对象存储后再传 URL。

2.5.1 素材引用（asset://）

metadata.content 中可使用 asset://{AssetID} 引用素材库资产（AssetID 来自 CreateAsset / GetAsset，见 3.4 / 3.5）：

json

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "让画面中的人物缓缓转身微笑",
  "seconds": "5",
  "metadata": {
    "resolution": "480p",
    "ratio": "16:9",
    "content": [
      {
        "type": "image_url",
        "image_url": { "url": "asset://asset-20260618200812-mmq8g" },
        "role": "reference_image"
      }
    ]
  }
}

引用前建议 GetAsset 确认 Status=Active。

2.6 视频生视频

参考视频放在 metadata.content 的 video_url 条目中：

json

{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "修改一下这个视频",
  "seconds": "5",
  "metadata": {
    "resolution": "480p",
    "ratio": "16:9",
    "content": [
      {
        "type": "video_url",
        "video_url": { "url": "https://example.com/reference-video.mp4" },
        "role": "reference_video"
      }
    ]
  }
}

参考视频须为公网可访问 URL。

2.7 创建任务响应

json

{
  "id": "video_xxxxxxxxxxxxxxxx",
  "task_id": "video_xxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "progress": 0,
  "created_at": 1779607183
}

字段	说明
`id` / `task_id`	任务 ID（两者一致），后续轮询使用此值
`status`	创建后固定为 `queued`
`object`	固定 `video`

2.8 查询任务

GET /v1/video/generations/{task_id}
Authorization: Bearer <你的平台 Token>

响应为 { code, message, data } 结构。

进行中：

json

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "video_xxxxxxxxxxxxxxxx",
    "status": "IN_PROGRESS",
    "progress": "50%",
    "fail_reason": ""
  }
}

成功：

json

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "video_xxxxxxxxxxxxxxxx",
    "status": "SUCCESS",
    "result_url": "https://.../xxxxx.mp4?...",
    "progress": "100%",
    "data": {
      "usage": { "completion_tokens": 100858 }
    }
  }
}

失败：

json

{
  "code": "success",
  "data": {
    "task_id": "video_xxxxxxxxxxxxxxxx",
    "status": "FAILURE",
    "fail_reason": "视频格式不支持",
    "progress": "100%"
  }
}

字段	说明
`code`	接口调用结果，成功为 `success`（业务失败看 `data.status`）
`data.status`	`QUEUED` / `IN_PROGRESS` / `SUCCESS` / `FAILURE`
`data.result_url`	视频下载地址（有时效性，建议立即下载）
`data.fail_reason`	失败原因（`FAILURE` 时）
`data.progress`	进度百分比，如 `"50%"` / `"100%"`
`data.data.usage.completion_tokens`	本次消耗 token 数（计费依据）

2.9 状态说明

创建任务 → QUEUED → IN_PROGRESS → ┬─ SUCCESS → 下载视频
                                  └─ FAILURE

`data.status`	含义
`QUEUED`	排队中
`IN_PROGRESS`	生成中
`SUCCESS`	成功，见 `result_url`
`FAILURE`	失败，见 `fail_reason`

2.10 建议

轮询间隔建议 10 秒；视频生成通常需要 2~10 分钟。
创建任务建议 180 秒超时；查询建议 600 秒超时，偶发超时重试即可。
性价比推荐：480p + 16:9 + 5 秒。

三、素材库 API

素材库用于管理视频生成所需素材。统一入口 POST /api/material，通过 ?Action= 区分动作。

3.0 动作总览

Action	说明
`CreateAssetGroup`	创建素材组
`GetAssetGroup`	查询素材组
`DeleteAssetGroup`	删除素材组
`CreateAsset`	上传素材
`GetAsset`	查询素材
`DeleteAsset`	删除素材
`CreateVisualValidateSession`	创建真人认证 H5（见 3.8）
`GetVisualValidateResult`	查询真人认证结果（见 3.9）
`CreateRealValidateH5`	创建真人认证 H5 临时链接（见 3.10）

所有动作均为 POST /api/material?Action=<动作名>，请求体 JSON，响应为 ResponseMetadata + Result。

3.1 通用响应结构

json

{
  "ResponseMetadata": {
    "RequestId": "20260618...",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { }
}

字段	说明
`ResponseMetadata.RequestId`	请求唯一标识
`ResponseMetadata.Action`	本次动作名
`Result`	业务数据；失败时为 `{"Error":{...}}`

3.2 CreateAssetGroup — 创建素材组

POST /api/material?Action=CreateAssetGroup

参数	类型	必填	说明
`Name`	String	是	素材组名称
`Description`	String	否	描述

json

{ "Name": "我的素材组", "Description": "用于存放角色立绘" }

响应：Result.Id 为素材组 ID（形如 group-...）。

3.3 GetAssetGroup — 查询素材组

POST /api/material?Action=GetAssetGroup

参数	类型	必填	说明
`Id`	String	是	素材组 ID

json

{ "Id": "group-20260618195842-84j62" }

3.4 CreateAsset — 上传素材

POST /api/material?Action=CreateAsset

参数	类型	必填	说明
`GroupId`	String	是	素材组 ID
`URL`	String	是	公网可下载地址（`http`/`https`）
`Name`	String	是	素材名称
`AssetType`	String	是	`Image` / `Video` / `Audio`

json

{
  "GroupId": "group-20260618195842-84j62",
  "URL": "https://example.com/image.jpg",
  "Name": "角色立绘01",
  "AssetType": "Image"
}

同步处理，大文件可能耗时数分钟，客户端超时建议 ≥ 600 秒。返回 Result.Id 为资产 ID。

3.5 GetAsset — 查询素材

POST /api/material?Action=GetAsset

json

{ "Id": "asset-20260618200812-mmq8g" }

Result.Status：Active（可用）/ Pending（处理中）/ Failed（失败）。

3.6 DeleteAsset — 删除素材

json

{ "Id": "asset-20260618200812-mmq8g" }

3.7 DeleteAssetGroup — 删除素材组

json

{ "Id": "group-20260618195842-84j62" }

3.8 CreateVisualValidateSession — 创建真人认证 H5

POST /api/material?Action=CreateVisualValidateSession

请求体传 {} 即可。返回 BytedToken、H5Link、QrCode。

字段	说明
`Result.BytedToken`	轮询令牌，用于 `GetVisualValidateResult`（勿展示给终端用户）
`Result.H5Link`	H5 认证链接（约 5 分钟有效）
`Result.QrCode`	二维码（base64 PNG）

创建会话与后续轮询须使用同一 BytedToken。

3.9 GetVisualValidateResult — 查询真人认证结果

json

{ "BytedToken": "2026062515501465178B138B02A64E1A" }

完成后 Result.GroupId 为真人资产组 ID。轮询建议 3 秒间隔，最长 5 分钟。

3.10 CreateRealValidateH5 — 创建真人认证 H5（临时链接）

一次调用获取可发给终端用户的 H5 链接，全程不暴露 sk-：

json

{}

响应示例：

json

{
  "Result": {
    "H5Link": "https://stonerollai.com/rv?t=rt_xxxxxxxx",
    "ExpiresIn": 300
  }
}

H5 页面使用 rt_ 令牌调用：

POST /api/rv?Action=CreateVisualValidateSession
POST /api/rv?Action=GetVisualValidateResult

/api/rv 已开启 CORS；rt_ 令牌有效期由 ExpiresIn 决定。

3.11 素材文件限制

项目	限制
上传方式	仅公网 URL（`http`/`https`）
AssetType	`Image` / `Video` / `Audio`，须与文件类型一致
超时建议	CreateAsset 客户端超时 ≥ 600 秒

四、错误处理

4.1 业务错误

HTTP 200，业务体中带错误信息。

视频：data.status 为 FAILURE，见 fail_reason。
素材库：Result.Error，如 { "Code": "InternalError", "Message": "..." }。

4.2 服务端错误

HTTP 非 2xx：

json

{ "error": { "message": "错误描述", "type": "错误类型" } }

HTTP	含义与处理
401	Token 缺失或无效
400	请求体格式错误
404	路径错误，请使用 `/v1/video/generations` 或 `/api/material`
408 / 504	请求超时，可重试
429	请求过于频繁，请降频
502 / 503	服务暂时不可用，可重试或联系平台

五、注意事项

#	注意事项
1	视频生成为异步：创建后须轮询直到 `SUCCESS` 或 `FAILURE`。
2	视频下载地址有时效性（通常 24 小时内），请及时保存。
3	素材库动作用 `?Action=`，不要写成路径。
4	参数名区分大小写：视频用小写（`model`/`prompt`）；素材库用 PascalCase（`Name`/`GroupId`）。
5	业务失败看响应体，不要只看 HTTP 状态码。
6	`CreateAsset` 仅支持公网 URL，不支持二进制直传。
7	上传后轮询 `GetAsset` 至 `Active` 再用于视频生成。

六、调用示例（curl）

bash

# 视频生成 — 创建任务
curl -X POST "https://stonerollai.com/v1/video/generations" \
  -H "Authorization: Bearer <你的平台 Token>" \
  -H "Content-Type: application/json" \
  -d '{"model":"doubao-seedance-2-0-260128","prompt":"一只金色柴犬在樱花树下奔跑","seconds":"5","metadata":{"resolution":"480p","ratio":"16:9"}}'

# 视频生成 — 查询任务
curl "https://stonerollai.com/v1/video/generations/video_xxxxxxxx" \
  -H "Authorization: Bearer <你的平台 Token>"

# 素材库 — 创建素材组
curl -X POST "https://stonerollai.com/api/material?Action=CreateAssetGroup" \
  -H "Authorization: Bearer <你的平台 Token>" \
  -H "Content-Type: application/json" \
  -d '{"Name":"我的素材组","Description":"用于存放角色立绘"}'

# 素材库 — 上传素材
curl -X POST "https://stonerollai.com/api/material?Action=CreateAsset" \
  -H "Authorization: Bearer <你的平台 Token>" \
  -H "Content-Type: application/json" \
  -d '{"GroupId":"group-xxxxxxxx","URL":"https://example.com/image.jpg","Name":"角色立绘01","AssetType":"Image"}'

# 素材库 — 查询素材
curl -X POST "https://stonerollai.com/api/material?Action=GetAsset" \
  -H "Authorization: Bearer <你的平台 Token>" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-xxxxxxxx"}'

# 素材库 — 删除素材
curl -X POST "https://stonerollai.com/api/material?Action=DeleteAsset" \
  -H "Authorization: Bearer <你的平台 Token>" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-xxxxxxxx"}'

# 素材库 — 删除素材组
curl -X POST "https://stonerollai.com/api/material?Action=DeleteAssetGroup" \
  -H "Authorization: Bearer <你的平台 Token>" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-xxxxxxxx"}'

Seedance 2.0 API 对接文档 ​

一、通用说明 ​

1.1 接入地址 ​

1.2 认证方式 ​

1.3 计费说明 ​

1.4 接入补充 ​

二、视频生成 API ​

2.1 接口概览 ​

2.2 生成模式 ​

2.3 创建任务 — 请求字段 ​

2.3.1 metadata.content 条目与 role ​

2.4 文生视频 ​

2.5 图生视频 ​

2.5.1 素材引用（asset://） ​

2.6 视频生视频 ​

2.7 创建任务响应 ​

2.8 查询任务 ​

2.9 状态说明 ​

2.10 建议 ​

三、素材库 API ​

3.0 动作总览 ​

3.1 通用响应结构 ​

3.2 CreateAssetGroup — 创建素材组 ​

3.3 GetAssetGroup — 查询素材组 ​

3.4 CreateAsset — 上传素材 ​

3.5 GetAsset — 查询素材 ​

3.6 DeleteAsset — 删除素材 ​

3.7 DeleteAssetGroup — 删除素材组 ​

3.8 CreateVisualValidateSession — 创建真人认证 H5 ​

3.9 GetVisualValidateResult — 查询真人认证结果 ​

3.10 CreateRealValidateH5 — 创建真人认证 H5（临时链接） ​

3.11 素材文件限制 ​

四、错误处理 ​

4.1 业务错误 ​

4.2 服务端错误 ​

五、注意事项 ​

六、调用示例（curl） ​

Seedance 2.0 API 对接文档

一、通用说明

1.1 接入地址

1.2 认证方式

1.3 计费说明

1.4 接入补充

二、视频生成 API

2.1 接口概览

2.2 生成模式

2.3 创建任务 — 请求字段

2.3.1 metadata.content 条目与 role

2.4 文生视频

2.5 图生视频

2.5.1 素材引用（asset://）

2.6 视频生视频

2.7 创建任务响应

2.8 查询任务

2.9 状态说明

2.10 建议

三、素材库 API

3.0 动作总览

3.1 通用响应结构

3.2 CreateAssetGroup — 创建素材组

3.3 GetAssetGroup — 查询素材组

3.4 CreateAsset — 上传素材

3.5 GetAsset — 查询素材

3.6 DeleteAsset — 删除素材

3.7 DeleteAssetGroup — 删除素材组

3.8 CreateVisualValidateSession — 创建真人认证 H5

3.9 GetVisualValidateResult — 查询真人认证结果

3.10 CreateRealValidateH5 — 创建真人认证 H5（临时链接）

3.11 素材文件限制

四、错误处理

4.1 业务错误

4.2 服务端错误

五、注意事项

六、调用示例（curl）