Seedance 视频生成 API 文档

适用模型：Seedance 2.0 / 2.0-Fast / 2.0-Mini / 2.5 视频生成模型.
官方文档：https://docs.volcengine.com/docs/ark/create-video-generation-task-api?lang=zh

1. 接口

视频生成Base URL（将下方路径中的 {baseurl} 替换为对应环境地址）

国内：https://vg-api.aig-ai.com/v3/bytedance-cn

海外：https://vg-api.aig-ai.com/v3/bytedance

素材库BaseURL

国内：虚拟：https://vg-api.aig-ai.com/v3/bytedance-cn/virtual、真人：https://vg-api.aig-ai.com/v3/bytedance-cn/real

国外：虚拟：https://vg-api.aig-ai.com/v3/bytedance/virtual、真人：https://vg-api.aig-ai.com/v3/bytedance/real

鉴权：所有接口请求头需携带 Authorization: Bearer <API Key>，Content-Type: application/json。

功能	请求方法	路径	说明
创建视频生成任务	POST	`{baseurl}/api/v3/contents/generations/tasks`	提交视频生成任务，异步返回任务 ID，用于后续查询结果与状态。仅可查询最近 7 天的任务
查询视频生成任务	GET	`{baseurl}/api/v3/contents/generations/tasks/{task_id}`	根据任务 ID 查询生成状态与结果；状态为 `succeeded` 时，从 `content.video_url` 获取视频下载地址（有效期 24 小时）
创建虚拟素材组	POST	`{baseurl}?Action=CreateAssetGroup&Version=2024-01-01`	创建虚拟人像素材组（AIGC）
查询虚拟素材组	POST	`{baseurl}?Action=GetAssetGroup&Version=2024-01-01`	获取单个虚拟素材组信息
查询虚拟素材组列表	POST	`{baseurl}?Action=ListAssetGroups&Version=2024-01-01`	列出虚拟素材组
修改虚拟素材组	POST	`{baseurl}?Action=UpdateAssetGroup&Version=2024-01-01`	修改虚拟素材组名称 / 描述
删除虚拟素材组	POST	`{baseurl}?Action=DeleteAssetGroup&Version=2024-01-01`	删除虚拟素材组
上传虚拟素材	POST	`{baseurl}?Action=CreateAsset&Version=2024-01-01`	向虚拟素材组上传图片 / 视频 / 音频
获取虚拟素材	POST	`{baseurl}?Action=GetAsset&Version=2024-01-01`	获取单个虚拟素材并轮询处理状态
查询虚拟素材列表	POST	`{baseurl}?Action=ListAssets&Version=2024-01-01`	列出虚拟素材
修改虚拟素材	POST	`{baseurl}?Action=UpdateAsset&Version=2024-01-01`	修改虚拟素材名称
删除虚拟素材	POST	`{baseurl}?Action=DeleteAsset&Version=2024-01-01`	删除虚拟素材（不可逆）
创建活体认证会话	POST	`{baseurl}?Action=CreateVisualValidateSession&Version=2024-01-01`	创建真人 H5 活体认证会话，返回校验链接；真人素材组须由此流程生成
获取活体认证结果	POST	`{baseurl}?Action=GetVisualValidateResult&Version=2024-01-01`	用 BytedToken 换取真人素材组 ID
上传真人素材	POST	`{baseurl}?Action=CreateAsset&Version=2024-01-01`	向真人素材组上传图片
获取真人素材	POST	`{baseurl}?Action=GetAsset&Version=2024-01-01`	获取单个真人素材并轮询处理状态
查询真人素材列表	POST	`{baseurl}?Action=ListAssets&Version=2024-01-01`	列出真人素材

2. 参数

2.1 视频生成任务

创建视频生成任务

参数	类型	必填	默认值	含义
`model`	string	是	—	模型 ID，取值如：国内：doubao-seedance-2-0-260128 、 doubao-seedance-2-0-fast-260128 、 doubao-seedance-2-0-mini-260615、doubao-seedance-2-5-260628 海外：dreamina-seedance-2-0-260128 、 dreamina-seedance-2-0-fast-260128 、 dreamina-seedance-2-0-mini-260615 、dreamina-seedance-2-5-260628
`content`	object[]	是	—	输入内容列表，支持文本 / 图片 / 视频 / 音频 / 样片任务 ID 等组合；支持纯文本、文本+图片、文本+视频、文本+音频（仅 2.5 支持单独音频）、文本+图片+音频、文本+图片+视频、文本+图片+视频+音频等
`content[].type`	string	是	—	元素类型：`text` / `image_url` / `video_url` / `audio_url`
`content[].text`	string	type=`text` 时必填	—	文本提示词；中文不超过 500 字，英文不超过 1000 词；2.5 额外支持西班牙语、印尼语、葡语、日语、马来语、泰语、阿拉伯语、越南语、韩语
`content[].image_url`	object	否	—	`{"url":"..."}`，支持公网 URL / Base64 / 素材 ID `asset://`
`content[].video_url`	object	否	—	`{"url":"..."}`，支持公网 URL / Base64 / 素材 ID `asset://`
`content[].audio_url`	object	否	—	`{"url":"..."}`，支持公网 URL / Base64 / 虚拟人音频素材 ID `asset://`
`content[].role`	string	否	—	元素用途：`first_frame` / `last_frame` / `reference_image` / `reference_video`/`reference_audio`
`omni_reference_task_type`	string	否	`auto`	全模态参考任务类型引导；可传 `reference`（参考生视频）/ `edit`（编辑视频）/ `extend`（延长视频）/ `auto`（自动推断）
`resolution`	string	否	`720p`	`480p` / `720p` / `1080p`/`4k`
`ratio`	string	否	文生视频 `16:9`，图生视频 `adaptive`	宽高比：`16:9` / `4:3` / `1:1` / `3:4` / `9:16` / `21:9` / `adaptive`
`duration`	integer	否	—	视频时长（秒）；2.5 支持 4–30（或 `-1` 自动）；2.0 系列支持 2–15
`frames`	integer	否	—	视频帧数（与 `duration` 二选一）
`seed`	integer	否	`-1`	随机种子，`-1` 表示随机
`watermark`	boolean	否	`false`	是否添加水印
`generate_audio`	boolean	否	`true`	是否生成同步音频
`output_format`	string	否	`mp4`	输出格式；支持 `mp4` / `mov`
`callback_url`	string	否	—	任务状态变化时的回调地址（POST 推送；状态包括 `queued` / `running` / `succeeded` / `failed` / `expired`）
`return_last_frame`	boolean	否	`false`	是否返回尾帧图片 URL（用于连续视频拼接）
`execution_expires_after`	integer	否	`172800`	任务超时阈值（秒），范围 3600–259200（即 1 小时至 3 天）
`tools`	object[]	否	—	工具配置

说明：Seedance 2.5 / 2.0 系列不支持直接上传含真人脸的参考图 / 视频，须使用真人素材库（LivenessFace）或预置虚拟人像 / 已授权真人素材，以 asset:// 形式引用。

查询视频生成任务

参数	类型	必填	含义
`id`	string	是	任务 ID，路径参数（官方字段名为 `id`，非 `task_id`）

2.2 虚拟素材库

创建虚拟素材组（CreateAssetGroup）

参数	类型	必填	含义
`Name`	string	是	素材组名称，≤ 64 字符
`Description`	string	否	素材组描述，≤ 300 字符
`GroupType`	string	否	素材组类型，固定为 `AIGC`
`ProjectName`	string	否	所属项目，默认 `default`

查询虚拟素材组（GetAssetGroup）

参数	类型	必填	含义
`Id`	string	是	素材组 ID
`ProjectName`	string	否	所属项目，默认 `default`

查询虚拟素材组列表（ListAssetGroups）

参数	类型	必填	含义
`Filter.GroupIds`	array	否	按素材组 ID 列表过滤
`Filter.GroupType`	string	否	素材组类型，固定 `AIGC`
`Filter.Name`	string	否	按名称模糊匹配
`PageNumber`	integer	否	页码，从 1 开始，默认 1
`PageSize`	integer	否	每页数量，默认 10，最大 100
`ProjectName`	string	否	所属项目，默认 `default`

修改虚拟素材组（UpdateAssetGroup）

参数	类型	必填	含义
`Id`	string	是	素材组 ID
`Name`	string	否	新名称
`Description`	string	否	新描述
`ProjectName`	string	否	所属项目

删除虚拟素材组（DeleteAssetGroup）

参数	类型	必填	含义
`Id`	string	是	素材组 ID
`ProjectName`	string	否	所属项目

上传虚拟素材（CreateAsset）

参数	类型	必填	含义
`GroupId`	string	是	所属素材组 ID
`URL`	string	是	素材公网 URL（图片 / 视频 / 音频）
`AssetType`	string	是	素材类型：`Image` / `Video` / `Audio`
`Name`	string	否	素材名称，≤ 64 字符
`ProjectName`	string	否	所属项目，默认 `default`

获取虚拟素材（GetAsset）

参数	类型	必填	含义
`Id`	string	是	素材 ID
`ProjectName`	string	否	所属项目

查询虚拟素材列表（ListAssets）

参数	类型	必填	含义
`Filter.GroupIds`	array	否	按素材组 ID 列表过滤
`Filter.GroupType`	string	否	素材组类型，虚拟素材固定 `AIGC`
`Filter.Statuses`	array	否	按状态过滤：`Active` / `Processing` / `Failed`
`Filter.Name`	string	否	按名称模糊匹配
`PageNumber`	integer	否	页码，从 1 开始，默认 1
`PageSize`	integer	否	每页数量，默认 10，最大 100
`ProjectName`	string	否	所属项目

修改虚拟素材（UpdateAsset）

参数	类型	必填	含义
`Id`	string	是	素材 ID
`Name`	string	否	新名称
`ProjectName`	string	否	所属项目

删除虚拟素材（DeleteAsset）

参数	类型	必填	含义
`Id`	string	是	素材 ID
`ProjectName`	string	否	所属项目

2.3 真人素材库

创建活体认证会话（CreateVisualValidateSession）

参数	类型	必填	含义
`CallbackURL`	string	是	活体认证完成后的回调地址
`ProjectName`	string	否	所属项目，默认 `default`

获取活体认证结果（GetVisualValidateResult）

参数	类型	必填	含义
`BytedToken`	string	是	创建会话时返回的 BytedToken
`ProjectName`	string	否	所属项目

上传真人素材（CreateAsset）

参数	类型	必填	含义
`GroupId`	string	是	所属真人素材组 ID
`URL`	string	是	素材公网 URL（图片）
`AssetType`	string	是	素材类型，固定 `Image`
`Name`	string	否	素材名称，≤ 64 字符
`ProjectName`	string	否	所属项目，默认 `default`

获取真人素材（GetAsset）

参数	类型	必填	含义
`Id`	string	是	素材 ID
`ProjectName`	string	否	所属项目

查询真人素材列表（ListAssets）

参数	类型	必填	含义
`Filter.GroupIds`	array	否	按素材组 ID 列表过滤
`Filter.GroupType`	string	否	素材组类型，真人素材固定 `LivenessFace`
`Filter.Statuses`	array	否	按状态过滤：`Active` / `Processing` / `Failed`
`Filter.Name`	string	否	按名称模糊匹配
`PageNumber`	integer	否	页码，从 1 开始，默认 1
`PageSize`	integer	否	每页数量，默认 10，最大 100
`ProjectName`	string	否	所属项目

素材状态说明：Processing（处理中，尚不可用）→ Active（可用，以 asset:// 引用）→ Failed（处理失败）。上传后请轮询 GetAsset 至 Active 再用于视频生成。

3. 请求示例

3.1 视频生成任务

创建视频生成任务（国内）

查询视频生成任务（海外）

3.2 虚拟素材库

创建虚拟素材组（国内）

上传虚拟素材

获取虚拟素材（轮询状态）

查询虚拟素材列表

3.3 真人素材库

创建活体认证会话（海外）

获取活体认证结果

上传真人素材

4. 响应示例

4.1 视频生成任务

创建视频生成任务

{
  "id": "cgt-20250918-0a1b2c3d4e",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "created_at": 1760000000,
  "updated_at": 1760000000,
  "content": { "video_url": null, "title": null },
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 5,
  "generate_audio": true,
  "watermark": false,
  "seed": -1,
  "service_tier": "default",
  "usage": { "total_tokens": 0 }
}

查询视频生成任务（status = succeeded）

{
  "id": "cgt-20250918-0a1b2c3d4e",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "created_at": 1760000000,
  "updated_at": 1760000120,
  "content": {
    "video_url": "https://ark-media.volces.com/.../video.mp4?X-Tos-Algorithm=...&X-Tos-Expires=86400",
    "title": ""
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "frames": 120,
  "framespersecond": 24,
  "generate_audio": true,
  "output_format": "mp4",
  "watermark": false,
  "seed": 11,
  "service_tier": "default",
  "usage": { "total_tokens": 108000 }
}

状态取值：queued / running / succeeded / failed / expired。失败时返回 error 对象（code / message）。

4.2 虚拟素材库

素材库接口响应均以 Result 对象包裹业务数据，外层附带标准 ResponseMetadata（含 RequestId、Action、Version 等）。以下示例仅展示 Result 部分。

创建虚拟素材组

{
  "Result": { "Id": "group-20260331145705-xxxxx" }
}

上传虚拟素材

{
  "Result": { "Id": "asset-20260318071009-xxxxx" }
}

获取虚拟素材

{
  "Result": {
    "Id": "asset-20260318071009-xxxxx",
    "Name": "front-face",
    "GroupId": "group-20260331145705-xxxxx",
    "AssetType": "Image",
    "Status": "Active",
    "URL": "https://ark-media.volces.com/.../portrait.png?X-Tos-...",
    "CreateTime": "2026-03-18T07:10:09Z",
    "UpdateTime": "2026-03-18T07:10:30Z"
  }
}

查询虚拟素材列表

{
  "Result": {
    "Items": [
      {
        "Id": "asset-20260318071009-xxxxx",
        "Name": "front-face",
        "GroupId": "group-20260331145705-xxxxx",
        "AssetType": "Image",
        "Status": "Active",
        "URL": "https://ark-media.volces.com/.../portrait.png?X-Tos-..."
      }
    ],
    "NextToken": "xxxxx"
  }
}

修改 / 删除类接口

{
  "Result": {}
}

4.3 真人素材库

创建活体认证会话

{
  "Result": {
    "BytedToken": "20260331145619CA67F03F8F...",
    "H5Link": "https://h5-v2.kych5.com?accessKeyId=...&sessionToken=...&bytedToken=...",
    "CallbackURL": "https://www.example.com/callback"
  }
}

获取活体认证结果

{
  "Result": { "GroupId": "group-20260331145705-xxxxx" }
}

上传真人素材 / 获取真人素材 / 查询真人素材列表

{
  "Result": { "Id": "asset-20260318071009-xxxxx" }
}

{
  "Result": {
    "Id": "asset-20260318071009-xxxxx",
    "Name": "self-front",
    "GroupId": "group-20260331145705-xxxxx",
    "AssetType": "Image",
    "Status": "Active",
    "URL": "https://ark-media.volces.com/.../selfie.png?X-Tos-..."
  }
}

1. 接口#

2. 参数#

2.1 视频生成任务#

2.2 虚拟素材库#

2.3 真人素材库#

3. 请求示例#

3.1 视频生成任务#

3.2 虚拟素材库#

3.3 真人素材库#

4. 响应示例#

4.1 视频生成任务#

4.2 虚拟素材库#

4.3 真人素材库#