版本:v1.1 | 更新日期:2026-11-02 | 适用环境:数眼智能公有云
asset://<AssetId> 引用,无需每次重复上传原始文件。| 能力 | 说明 |
|---|---|
| 素材组管理 | 按业务维度对素材进行分组,支持增删改查 |
| 素材托管 | 支持 Image / Video / Audio 三类资源的异步上传、状态查询、引用与删除 |
| 账号隔离 | 所有资源以账号为隔离边界,同一账号下的所有 API Key 共享同一套素材库,跨账号资源不可互访 |
| 内容审核 | 素材上传后自动进行内容安全审核,仅审核通过(Active 状态)的素材可参与视频生成 |
| 环境 | 地址 |
|---|---|
| 数眼智能 | https://platform.shuyanai.com |
| 私有化部署 | 由部署方提供,按合同约定 |
www.shuyanai.com/admin/tokens)创建 Key。建议为不同业务线分配独立 Key,便于审计与限流。Authorization: Bearer sk-xxx| 场景 | HTTP 状态码 | 响应体 |
|---|---|---|
| 未提供 Key | 401 | {"error":{"code":"","message":"未提供令牌 (request id: ...)","type":"server_error"}} |
| Key 无效或已禁用 | 401 | {"error":{"code":"","message":"无效的令牌 (request id: ...)","type":"server_error"}} |
Action 区分操作类型:POST https://platform.shuyanai.com/seedance?Action=<ActionName>&Version=2024-01-01| 参数 | 说明 |
|---|---|
Action | 操作名称,区分大小写。如 CreateAssetGroup、ListAssets |
Version | API 版本号,当前固定为 2024-01-01 |
POST /seedance/api/v3/contents/generations/tasks
GET /seedance/api/v3/contents/generations/tasks/{task_id}application/jsonGroupId、AssetType);视频生成接口使用 snake_case(如 image_url、generate_audio)Result 中。{
"Result": {
"Id": "group-20260624152835-lb6rn"
}
}ListAssetGroups、ListAssets)额外返回 ResponseMetadata:{
"ResponseMetadata": {
"Action": "ListAssetGroups",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [],
"TotalCount": 0,
"PageNumber": 1,
"PageSize": 10
}
}ResponseMetadata):{
"error": "resource not found or not owned by user"
}ResponseMetadata.Error):{
"ResponseMetadata": {
"RequestId": "...",
"Action": "CreateAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing",
"Error": {
"Code": "MissingParameter.Name",
"Message": "The required parameter Name is missing."
}
}
}| 资源类型 | 格式 | 示例 |
|---|---|---|
| 素材组 | group-<YYYYMMDDHHmmss>-<随机后缀> | group-20260624152835-lb6rn |
| 素材 | asset-<YYYYMMDDHHmmss>-<随机后缀> | asset-20260624152850-mftbb |
| 视频任务 | cgt-<YYYYMMDDHHmmss>-<随机后缀> | cgt-20260624152927-ptz2s |
POST /seedance?Action=CreateAssetGroup&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Name | string | 是 | 素材组名称,1 ~ 64 字符 |
| Description | string | 否 | 素材组描述,最长 256 字符 |
| GroupType | string | 否 | 素材组类型,默认 AIGC,当前仅支持 AIGC |
| 参数 | 类型 | 说明 |
|---|---|---|
| Result.Id | string | 新建素材组 ID |
{
"Result": {
"Id": "group-20260624152835-lb6rn"
}
}POST /seedance?Action=ListAssetGroups&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| PageNumber | integer | 否 | 页码,默认 1,从 1 开始 |
| PageSize | integer | 否 | 每页条数,默认 10,最大 100 |
| Filter.Name | string | 否 | 名称模糊匹配 |
| Filter.Statuses | string[] | 否 | 状态过滤:Processing / Active / Failed |
| 参数 | 类型 | 说明 |
|---|---|---|
| Result.TotalCount | integer | 命中总数 |
| Result.PageNumber | integer | 当前页码 |
| Result.PageSize | integer | 当前页大小 |
| Result.Items[] | array | 素材组列表 |
| Result.Items[].Id | string | 素材组 ID |
| Result.Items[].Name | string | 素材组名称 |
| Result.Items[].Description | string | 素材组描述 |
| Result.Items[].GroupType | string | 类型,固定 AIGC |
| Result.Items[].Status | string | 素材组状态:Processing / Active / Failed |
{
"ResponseMetadata": {
"Action": "ListAssetGroups",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 10,
"Items": [
{
"Id": "group-20260624152835-lb6rn",
"Name": "brand_visual_lib",
"Description": "品牌视觉资产库",
"GroupType": "AIGC",
"Status": "Active"
}
]
}
}POST /seedance?Action=GetAssetGroup&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材组 ID |
Items[]。{
"Result": {
"Id": "group-20260624152835-lb6rn",
"Name": "brand_visual_lib",
"Description": "品牌视觉资产库",
"GroupType": "AIGC",
"Status": "Active"
}
}GroupType 创建后不可变更。POST /seedance?Action=UpdateAssetGroup&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材组 ID |
| Name | string | 否 | 新名称,1 ~ 64 字符 |
| Description | string | 否 | 新描述,最长 256 字符 |
{
"Result": {
"Id": "group-20260624152835-lb6rn"
}
}POST /seedance?Action=DeleteAssetGroup&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材组 ID |
{
"Result": {
"Id": "group-20260624152835-lb6rn"
}
}Active 后方可在视频生成中引用。POST /seedance?Action=CreateAsset&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| GroupId | string | 是 | 所属素材组 ID |
| URL | string | 是 | 素材公网可访问地址 |
| AssetType | string | 是 | 素材类型:Image / Video / Audio |
| Name | string | 否 | 素材名称,1 ~ 64 字符。仅用于 ListAssets 模糊搜索,不会被带入模型推理 |
| 参数 | 类型 | 说明 |
|---|---|---|
| Result.Id | string | 新建素材 ID |
{
"Result": {
"Id": "asset-20260624152850-mftbb"
}
}提示:上传后请轮询素材状态。图片资源通常 3 ~ 10 秒内变为 Active,视频和音频可能需要更长时间。
POST /seedance?Action=ListAssets&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Filter.GroupIds | string[] | 否 | 按素材组 ID 过滤 |
| Filter.Statuses | string[] | 否 | 状态过滤:Processing / Active / Failed |
| Filter.Name | string | 否 | 名称模糊匹配 |
| PageNumber | integer | 否 | 页码,默认 1 |
| PageSize | integer | 否 | 每页条数,默认 10,最大 100 |
说明:请求体中 Filter为嵌套对象,参数表中使用点号表示层级关系。例如Filter.Statuses对应请求体中的{"Filter": {"Statuses": [...]}}。
| 参数 | 类型 | 说明 |
|---|---|---|
| Result.TotalCount | integer | 命中总数 |
| Result.PageNumber | integer | 当前页码 |
| Result.PageSize | integer | 当前页大小 |
| Result.Items[] | array | 素材列表 |
| Result.Items[].Id | string | 素材 ID |
| Result.Items[].Name | string | 素材名称 |
| Result.Items[].Description | string | 素材描述 |
| Result.Items[].URL | string | 上传素材时提交的源地址 |
| Result.Items[].AssetType | string | 素材类型 |
| Result.Items[].GroupId | string | 所属素材组 ID |
| Result.Items[].Status | string | 状态:Processing / Active / Failed |
{
"ResponseMetadata": {
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"TotalCount": 1,
"PageNumber": 1,
"PageSize": 10,
"Items": [
{
"Id": "asset-20260624152850-mftbb",
"Name": "产品主图",
"Description": "",
"URL": "https://example.com/product-photo.png",
"AssetType": "Image",
"GroupId": "group-20260624152835-lb6rn",
"Status": "Active"
}
]
}
}POST /seedance?Action=GetAsset&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材 ID |
Items[]。{
"Result": {
"Id": "asset-20260624152850-mftbb",
"Name": "产品主图",
"Description": "",
"URL": "https://example.com/product-photo.png",
"AssetType": "Image",
"GroupId": "group-20260624152835-lb6rn",
"Status": "Active"
}
}| 阶段 | 间隔 | 说明 |
|---|---|---|
| 首次查询 | 3 秒后 | 图片通常 3 ~ 10 秒完成 |
| 后续查询 | 指数退避至 10 秒 | 视频 / 音频可能需要更长时间 |
| 超时退出 | 5 分钟 | 超时仍为 Processing,请检查源 URL 可访问性 |
POST /seedance?Action=UpdateAsset&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材 ID |
| Name | string | 否 | 新名称,1 ~ 64 字符 |
{
"Result": {
"Id": "asset-20260624152850-mftbb"
}
}POST /seedance?Action=DeleteAsset&Version=2024-01-01| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材 ID |
{
"Result": {
"Id": "asset-20260624152850-mftbb"
}
}Active 后,可在 Seedance 视频生成接口中通过 asset://<AssetId> 引用。POST /seedance/api/v3/contents/generations/tasks| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名称,如 doubao-seedance-2-0-260128 |
| content | array | 是 | 内容数组,包含文本描述和素材引用 |
| content[].type | string | 是 | 内容类型:text、image_url、video_url、audio_url |
| content[].text | string | 条件 | 当 type=text 时必填,视频描述文本 |
| content[].role | string | 条件 | 素材角色,如 reference_image、reference_video、reference_audio |
| content[].image_url.url | string | 条件 | 当 type=image_url 时必填,支持 asset://<AssetId> 或公网 URL |
| ratio | string | 否 | 画面比例,如 16:9、9:16、1:1 |
| duration | integer | 否 | 视频时长(秒),如 5、10 |
| watermark | boolean | 否 | 是否添加水印,默认 false |
| generate_audio | boolean | 否 | 是否生成有声视频,默认 true |
完整参数见01-创建视频生成任务。
素材引用方式:在 content数组中通过asset://<AssetId>传入素材,在 prompt 文本中使用"图片 1、视频 1、音频 1"等序号指代(序号为该素材在同类素材中的出现顺序)。请勿在 prompt 中直接使用 Asset ID。
{
"id": "cgt-20260624152927-ptz2s"
}GET /seedance/api/v3/contents/generations/tasks/{task_id}| 参数 | 类型 | 说明 |
|---|---|---|
| id | string | 任务 ID |
| model | string | 使用的模型 |
| status | string | 任务状态:queued / running / succeeded / failed / cancelled / expired |
| content.video_url | string | 视频下载链接(succeeded 时返回),有效期 24 小时 |
| usage.completion_tokens | integer | 生成消耗的 Token 数 |
| usage.total_tokens | integer | 总消耗 Token 数 |
| created_at | integer | 任务创建时间(Unix 时间戳,秒) |
| updated_at | integer | 任务更新时间(Unix 时间戳,秒) |
| seed | integer | 本次生成的随机种子 |
| resolution | string | 输出分辨率,如 720p |
| ratio | string | 画面比例 |
| duration | integer | 视频 时长(秒) |
| framespersecond | integer | 帧率,默认 24 |
| service_tier | string | 服务等级 |
| execution_expires_after | integer | 任务超时阈值(秒),默认 172800(48 小时) |
| generate_audio | boolean | 是否生成有声视频 |
{
"id": "cgt-20260624152927-ptz2s",
"model": "doubao-seedance-2-0-260128",
"status": "running",
"created_at": 1782286167,
"updated_at": 1782286167,
"service_tier": "default",
"execution_expires_after": 172800,
"generate_audio": true,
"draft": false,
"priority": 0
}{
"id": "cgt-20260624152927-ptz2s",
"model": "doubao-seedance-2-0-260128",
"status": "succeeded",
"content": {
"video_url": "https://ark-acg-cn-beijing.tos-cn-beijing.volces.com/.../video.mp4?X-Tos-Algorithm=..."
},
"usage": {
"completion_tokens": 108900,
"total_tokens": 108900
},
"created_at": 1782286167,
"updated_at": 1782286432,
"seed": 77923,
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"framespersecond": 24,
"service_tier": "default",
"execution_expires_after": 172800,
"generate_audio": true,
"draft": false,
"priority": 0
}| 阶段 | 间隔 | 说明 |
|---|---|---|
| 初始 | 5 秒 | 排队期间查询可能只返回 id,视同排队中继续轮询 |
| 后续 | 10 秒 | 720p / 5 秒视频通常 3 ~ 5 分钟完成,分辨率越高、时长越长耗时越久 |
前置依赖:需安装 jq 命令行 JSON 工具。