Seedance 私域素材库 API 文档

版本：v1.0 | 发布日期：2026-06-24 | 适用环境：DataeyesAI 公有云

1. 概述

Seedance 私域素材库为视频生成场景提供可复用素材的集中托管能力。您可以通过 API 调用或在DataeyesAI控制台的「SD 素材库」页面上传图片、视频、音频至素材库，托管完成后在视频生成请求中通过 asset://<AssetId> 协议引用，无需每次重复上传原始文件。

核心能力

能力	说明
素材组管理	按业务维度对素材进行分组，支持增删改查
素材托管	支持 Image / Video / Audio 三类资源的异步上传、状态轮询、引用与删除
账号隔离	所有资源以账号为隔离边界，同一账号下的所有 API 令牌共享同一套素材库，跨账号资源不可互访
内容审核	素材上传后自动进行内容安全审核，仅审核通过（`Active` 状态）的素材可参与视频生成

典型场景

角色一致性：将稳定的人像素材上传为参考图，保证多镜头主角外观一致。
品牌资产复用：Logo、产品图、背景音乐等长期使用的素材统一托管，避免重复上传。
批量生成提速：素材一次上传、多次引用，节省重复下载与审核耗时。

2. 接入准备

2.1 服务地址

环境	地址
DataeyesAI（公有云）	`https://platform.dataeyes.ai`
私有化部署	由部署方提供，按合同约定

2.2 获取 API 令牌

登录DataeyesAI控制台，进入「API 令牌」模块创建令牌。建议为不同业务线分配独立令牌，便于审计与限流。

2.3 鉴权方式

所有请求必须在 HTTP 头中携带 API 令牌：

Authorization: Bearer <YOUR_API_KEY>

鉴权失败响应示例：

场景	HTTP 状态码	响应体
未提供令牌	401	`{"error":{"code":"","message":"未提供令牌 (request id: ...)","type":"server_error"}}`
令牌无效或已禁用	401	`{"error":{"code":"","message":"无效的令牌 (request id: ...)","type":"server_error"}}`

3. 通用协议

3.1 请求路由

素材库接口统一通过 Query 参数 Action 区分操作类型：

POST https://platform.dataeyes.ai/seedance?Action=<ActionName>&Version=2024-01-01

参数	说明
`Action`	操作名称，区分大小写。如 `CreateAssetGroup`、`ListAssets`
`Version`	API 版本号，当前固定为 `2024-01-01`

视频生成接口路径独立，不走 Action 路由：

POST /seedance/api/v3/contents/generations/tasks
GET  /seedance/api/v3/contents/generations/tasks/{task_id}

3.2 请求格式

Content-Type：application/json
字段命名：素材库接口使用 PascalCase（如 GroupId、AssetType）；视频生成接口使用 snake_case（如 image_url、generate_audio）

3.3 响应格式

成功响应：

{
  "ResponseMetadata": {
    "RequestId": "2026062415283493B3836D523A0F3F0AFB",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260624152835-lb6rn"
  }
}

ResponseMetadata.RequestId：本次请求的唯一标识。排查问题时请务必提供此字段。
Result：业务数据，结构按各接口定义。

失败响应有两种形态：

形态一 — 网关层错误（鉴权失败、资源权限校验等，不含 ResponseMetadata）：

{
  "error": "resource does not belong to current 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."
    }
  }
}

3.4 时间格式

所有时间字段为 UTC 时区，ISO 8601 格式：2026-06-24T07:28:35Z。

3.5 资源 ID 格式

资源类型	格式	示例
素材组	`group-<YYYYMMDDHHmmss>-<5位随机>`	`group-20260624152835-lb6rn`
素材	`asset-<YYYYMMDDHHmmss>-<5位随机>`	`asset-20260624152850-mftbb`
视频任务	`cgt-<YYYYMMDDHHmmss>-<5位随机>`	`cgt-20260624152927-ptz2s`

4. 素材组接口

素材组是素材的逻辑容器，用于按业务维度对素材进行分类管理。

4.1 创建素材组 CreateAssetGroup

创建一个素材分组容器。

请求：

POST /seedance?Action=CreateAssetGroup&Version=2024-01-01

请求参数：

参数	类型	必填	说明
Name	string	是	素材组名称，1 ~ 64 字符
Description	string	否	素材组描述，最长 256 字符
GroupType	string	否	素材组类型，默认 `AIGC`，当前仅支持 `AIGC`

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=CreateAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Name": "brand_visual_lib",
    "Description": "品牌视觉资产库",
    "GroupType": "AIGC"
  }'

响应参数：

参数	类型	说明
Result.Id	string	新建素材组 ID

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "2026062415283493B3836D523A0F3F0AFB",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260624152835-lb6rn"
  }
}

4.2 查询素材组列表 ListAssetGroups

分页查询当前账号名下的素材组。系统自动按账号注入隔离条件，无需手动传入过滤参数。

请求：

POST /seedance?Action=ListAssetGroups&Version=2024-01-01

请求参数：

参数	类型	必填	说明
PageNumber	integer	否	页码，默认 `1`，从 1 开始
PageSize	integer	否	每页条数，默认 `10`，最大 `100`
Filter.GroupType	string	否	类型过滤，默认 `AIGC`

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=ListAssetGroups&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "PageNumber": 1,
    "PageSize": 10
  }'

响应参数：

参数	类型	说明
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	类型
Result.Items[].ProjectName	string	所属项目
Result.Items[].CreateTime	string	创建时间（UTC）
Result.Items[].UpdateTime	string	更新时间（UTC）

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "2026062415282793B3836D523A0F3F0A8E",
    "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",
        "ProjectName": "default",
        "CreateTime": "2026-06-24T07:28:35Z",
        "UpdateTime": "2026-06-24T07:28:35Z"
      }
    ]
  }
}

4.3 查询素材组详情 GetAssetGroup

查询单个素材组的详细信息。

请求：

POST /seedance?Action=GetAssetGroup&Version=2024-01-01

请求参数：

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

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=GetAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "group-20260624152835-lb6rn"
  }'

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "2026062415284193B3836D523A0F3F0B63",
    "Action": "GetAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260624152835-lb6rn",
    "Name": "brand_visual_lib",
    "Description": "品牌视觉资产库",
    "GroupType": "AIGC",
    "ProjectName": "default",
    "CreateTime": "2026-06-24T07:28:35Z",
    "UpdateTime": "2026-06-24T07:28:35Z"
  }
}

4.4 更新素材组 UpdateAssetGroup

更新素材组的名称或描述。GroupType 创建后不可变更。

请求：

POST /seedance?Action=UpdateAssetGroup&Version=2024-01-01

请求参数：

参数	类型	必填	说明
Id	string	是	素材组 ID
Name	string	否	新名称，1 ~ 64 字符
Description	string	否	新描述，最长 256 字符

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=UpdateAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "group-20260624152835-lb6rn",
    "Name": "brand_visual_lib_v2",
    "Description": "品牌视觉资产库（升级版）"
  }'

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "202606241529076954A62A765732A09740",
    "Action": "UpdateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260624152835-lb6rn"
  }
}

4.5 删除素材组 DeleteAssetGroup

删除素材组。建议删除前先调用 ListAssets 确认组内素材已清理完毕。

请求：

POST /seedance?Action=DeleteAssetGroup&Version=2024-01-01

请求参数：

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

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=DeleteAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "group-20260624152835-lb6rn"
  }'

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "2026062415293548C21A8020C8E8AEA0B3",
    "Action": "DeleteAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260624152835-lb6rn"
  }
}

5. 素材接口

5.1 上传素材 CreateAsset

从公网 URL 拉取资源并入库。本接口为异步接口，返回成功仅表示任务已受理；需轮询 GetAsset 直至状态变为 Active 后方可在视频生成中引用。

请求：

POST /seedance?Action=CreateAsset&Version=2024-01-01

请求参数：

参数	类型	必填	说明
GroupId	string	是	所属素材组 ID
URL	string	是	素材公网可访问地址
AssetType	string	是	素材类型：`Image` / `Video` / `Audio`
Name	string	否	素材名称，1 ~ 64 字符。仅用于 `ListAssets` 模糊搜索，不会被带入模型推理

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "group-20260624152835-lb6rn",
    "URL": "https://example.com/product-photo.png",
    "AssetType": "Image",
    "Name": "产品主图"
  }'

响应参数：

参数	类型	说明
Result.Id	string	新建素材 ID

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "202606241528476954A62A765732A0969D",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260624152850-mftbb"
  }
}

提示：上传完成后请立即轮询素材状态。图片资源通常 3 ~ 10 秒内变为 Active，视频和音频可能需要更长时间。

5.2 查询素材列表 ListAssets

分页查询素材，支持按状态、名称、类型过滤与排序。系统自动按账号注入隔离条件。

请求：

POST /seedance?Action=ListAssets&Version=2024-01-01

请求参数：

参数	类型	必填	说明
Filter.Statuses	string[]	否	状态过滤：`Processing` / `Active` / `Failed`
Filter.Name	string	否	名称模糊匹配
Filter.AssetType	string	否	类型过滤：`Image` / `Video` / `Audio`
PageNumber	integer	否	页码，默认 `1`
PageSize	integer	否	每页条数，默认 `10`，最大 `100`
SortBy	string	否	排序字段，当前支持 `CreateTime`
SortOrder	string	否	排序方向：`Asc` 或 `Desc`（默认）

说明：请求体中 Filter 为嵌套对象，参数表中使用点号表示层级关系。例如 Filter.Statuses 对应请求体中的 {"Filter": {"Statuses": [...]}} 。

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=ListAssets&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Filter": {
      "Statuses": ["Active", "Processing"]
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc"
  }'

响应参数：

参数	类型	说明
Result.TotalCount	integer	命中总数
Result.PageNumber	integer	当前页码
Result.PageSize	integer	当前页大小
Result.Items[]	array	素材列表
Result.Items[].Id	string	素材 ID
Result.Items[].Name	string	素材名称
Result.Items[].URL	string	临时下载链接（仅 `Active` 状态返回，有效期 12 小时）
Result.Items[].AssetType	string	素材类型
Result.Items[].GroupId	string	所属素材组 ID
Result.Items[].Status	string	状态：`Processing` / `Active` / `Failed`
Result.Items[].Moderation	object	审核信息
Result.Items[].Moderation.Strategy	string	审核策略，默认 `Default`
Result.Items[].CreateTime	string	创建时间（UTC）
Result.Items[].UpdateTime	string	更新时间（UTC）
Result.Items[].ProjectName	string	所属项目

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "202606241528566954A62A765732A096EC",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "TotalCount": 5,
    "PageNumber": 1,
    "PageSize": 10,
    "Items": [
      {
        "Id": "asset-20260624152850-mftbb",
        "Name": "产品主图",
        "URL": "https://ark-media-asset.tos-cn-beijing.volces.com/.../product.png?X-Tos-Algorithm=...",
        "AssetType": "Image",
        "GroupId": "group-20260624152835-lb6rn",
        "Status": "Active",
        "Moderation": { "Strategy": "Default" },
        "CreateTime": "2026-06-24T07:28:50Z",
        "UpdateTime": "2026-06-24T07:28:52Z",
        "ProjectName": "default"
      }
    ]
  }
}

注意：URL 字段在素材状态为 Processing 时为空字符串 ""；变为 Active 后返回带时效签名的临时下载链接（默认 12 小时有效）。过期后重新调用 GetAsset 即可获取新链接。

5.3 查询素材详情 GetAsset

查询单个素材的详细信息。主要用于上传后轮询素材处理状态。

请求：

POST /seedance?Action=GetAsset&Version=2024-01-01

请求参数：

参数	类型	必填	说明
Id	string	是	素材 ID

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=GetAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "asset-20260624152850-mftbb"
  }'

响应参数：

参数	类型	说明
Result.Id	string	素材 ID
Result.Name	string	素材名称
Result.URL	string	临时下载链接（仅 `Active` 状态返回，有效期 12 小时）
Result.AssetType	string	素材类型
Result.GroupId	string	所属素材组 ID
Result.Status	string	状态：`Processing` / `Active` / `Failed`
Result.Moderation	object	审核信息
Result.Moderation.Strategy	string	审核策略
Result.CreateTime	string	创建时间（UTC）
Result.UpdateTime	string	更新时间（UTC）
Result.ProjectName	string	所属项目

响应示例（Active 状态）：

{
  "ResponseMetadata": {
    "RequestId": "2026062415285732FCC6E4F3BC2FAF6887",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260624152850-mftbb",
    "Name": "产品主图",
    "URL": "https://ark-media-asset.tos-cn-beijing.volces.com/.../product.png?X-Tos-Algorithm=...",
    "AssetType": "Image",
    "GroupId": "group-20260624152835-lb6rn",
    "Status": "Active",
    "Moderation": { "Strategy": "Default" },
    "CreateTime": "2026-06-24T07:28:50Z",
    "UpdateTime": "2026-06-24T07:28:52Z",
    "ProjectName": "default"
  }
}

轮询策略建议：

阶段	间隔	说明
首次查询	3 秒后	图片通常 3 ~ 10 秒完成
后续查询	指数退避至 10 秒	视频 / 音频可能需要更长时间
超时退出	5 分钟	超时仍为 Processing，请检查源 URL 可访问性

5.4 更新素材 UpdateAsset

更新素材名称。素材的 URL、类型、所属素材组均不可变更，如需更换请删除后重新上传。

请求：

POST /seedance?Action=UpdateAsset&Version=2024-01-01

请求参数：

参数	类型	必填	说明
Id	string	是	素材 ID
Name	string	否	新名称，1 ~ 64 字符

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=UpdateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "asset-20260624152850-mftbb",
    "Name": "产品主图-2026版"
  }'

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "202606241529076954A62A765732A09740",
    "Action": "UpdateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260624152850-mftbb"
  }
}

5.5 删除素材 DeleteAsset

物理删除素材，不可恢复。已被进行中的视频生成任务引用的素材不建议立即删除，否则可能导致生成失败。

请求：

POST /seedance?Action=DeleteAsset&Version=2024-01-01

请求参数：

参数	类型	必填	说明
Id	string	是	素材 ID

请求示例：

curl -X POST 'https://platform.dataeyes.ai/seedance?Action=DeleteAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Id": "asset-20260624152850-mftbb"
  }'

响应示例：

{
  "ResponseMetadata": {
    "RequestId": "202606241529296954A62A765732A097E8",
    "Action": "DeleteAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}

6. 在视频生成中引用素材

素材状态变为 Active 后，可在 Seedance 视频生成接口中通过 asset://<AssetId> 协议引用。

6.1 提交视频生成任务

请求：

POST /seedance/api/v3/contents/generations/tasks

请求参数：

参数	类型	必填	说明
model	string	是	模型名称，如 `doubao-seedance-2-0-260128`
content	array	是	内容数组，包含文本描述和素材引用
content[].type	string	是	内容类型：`text` 或 `image_url`
content[].text	string	条件	当 `type=text` 时必填，视频描述文本
content[].role	string	条件	当 `type=image_url` 时可选，素材角色（如 `reference_image`）
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	否	是否生成音频，默认 `false`

素材引用方式：在 content 数组中通过 asset://<AssetId> 传入素材，在 prompt 文本中使用"图片 1、视频 1、音频 1"等序号指代（序号为该素材在同类素材中的出现顺序）。请勿在 prompt 中直接使用 Asset ID。

请求示例：
-H 'Authorization: Bearer <YOUR_API_KEY>'
-H 'Content-Type: application/json'
-d '{
"model": "doubao-seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "镜头缓缓推近，画面元素轻微动起来，光影自然变化"
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260624152850-mftbb"
}
}
],
"ratio": "16:9",
"duration": 5,
"watermark": false,
"generate_audio": true
}'


**响应示例**：

```json
{
  "id": "cgt-20260624152927-ptz2s"
}

6.2 查询视频生成结果

视频生成为异步任务，提交后需轮询查询结果。

请求：

GET /seedance/api/v3/contents/generations/tasks/{task_id}

请求示例：

curl -X GET 'https://platform.dataeyes.ai/seedance/api/v3/contents/generations/tasks/cgt-20260624152927-ptz2s' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

响应参数：

参数	类型	说明
id	string	任务 ID
model	string	使用的模型
status	string	任务状态：`queued` / `running` / `succeeded` / `failed` / `cancelled`
content.video_url	string	视频下载链接（`succeeded` 时返回），带时效签名，默认 48 小时有效
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 秒	短视频（5s / 720p）通常 1 ~ 3 分钟完成
后续	10 秒	4K 分辨率可能需要 30 分钟以上

7. 端到端调用示例

以下脚本演示完整的「创建素材组 → 上传素材 → 等待就绪 → 生成视频 → 获取结果」流程。

前置依赖：需安装 jq 命令行 JSON 工具。

#!/bin/bash
set -e

API_KEY="<YOUR_API_KEY>"
BASE_URL="https://platform.dataeyes.ai"
AUTH_HEADER="Authorization: Bearer $API_KEY"

# ===== Step 1: 创建素材组 =====
echo ">>> 创建素材组..."
GROUP_ID=$(curl -s -X POST "$BASE_URL/seedance?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "$AUTH_HEADER" -H 'Content-Type: application/json' \
  -d '{"Name":"demo_group","GroupType":"AIGC"}' \
  | jq -r '.Result.Id')
echo "素材组 ID: $GROUP_ID"

# ===== Step 2: 上传素材 =====
echo ">>> 上传素材..."
ASSET_ID=$(curl -s -X POST "$BASE_URL/seedance?Action=CreateAsset&Version=2024-01-01" \
  -H "$AUTH_HEADER" -H 'Content-Type: application/json' \
  -d "{\"GroupId\":\"$GROUP_ID\",\"URL\":\"https://example.com/photo.png\",\"AssetType\":\"Image\",\"Name\":\"示例图片\"}" \
  | jq -r '.Result.Id')
echo "素材 ID: $ASSET_ID"

# ===== Step 3: 轮询素材状态至 Active =====
echo ">>> 等待素材审核..."
RETRY=0
while [ $RETRY -lt 30 ]; do
  STATUS=$(curl -s -X POST "$BASE_URL/seedance?Action=GetAsset&Version=2024-01-01" \
    -H "$AUTH_HEADER" -H 'Content-Type: application/json' \
    -d "{\"Id\":\"$ASSET_ID\"}" | jq -r '.Result.Status')
  echo "  素材状态: $STATUS"
  [ "$STATUS" = "Active" ] && break
  [ "$STATUS" = "Failed" ] && { echo "素材审核未通过"; exit 1; }
  sleep 3
  RETRY=$((RETRY + 1))
done

# ===== Step 4: 提交视频生成 =====
echo ">>> 提交视频生成..."
TASK_ID=$(curl -s -X POST "$BASE_URL/seedance/api/v3/contents/generations/tasks" \
  -H "$AUTH_HEADER" -H 'Content-Type: application/json' \
  -d "{
    \"model\":\"doubao-seedance-2-0-260128\",
    \"content\":[
      {\"type\":\"text\",\"text\":\"镜头缓缓推近，画面元素轻微动起来\"},
      {\"type\":\"image_url\",\"role\":\"reference_image\",\"image_url\":{\"url\":\"asset://$ASSET_ID\"}}
    ],
    \"ratio\":\"16:9\",
    \"duration\":5
  }" | jq -r '.id')
echo "视频任务 ID: $TASK_ID"

# ===== Step 5: 轮询视频生成结果 =====
echo ">>> 等待视频生成..."
RETRY=0
while [ $RETRY -lt 60 ]; do
  RESP=$(curl -s -X GET "$BASE_URL/seedance/api/v3/contents/generations/tasks/$TASK_ID" \
    -H "$AUTH_HEADER")
  STATUS=$(echo "$RESP" | jq -r '.status')
  echo "  视频状态: $STATUS"
  if [ "$STATUS" = "succeeded" ]; then
    VIDEO_URL=$(echo "$RESP" | jq -r '.content.video_url')
    echo ">>> 生成完成！视频下载地址："
    echo "$VIDEO_URL"
    break
  fi
  [ "$STATUS" = "failed" ] && { echo "视频生成失败"; exit 1; }
  sleep 10
  RETRY=$((RETRY + 1))
done

8. 素材状态机

8.1 素材状态流转

            CreateAsset
                │
                ▼
        ┌───────────────┐    审核失败     ┌──────────┐
        │  Processing   │ ───────────────►│  Failed  │（不可恢复）
        └───────┬───────┘                 └──────────┘
                │ 审核通过
                ▼
        ┌───────────────┐
        │    Active     │  ── 可在视频生成中通过 asset:// 引用
        └───────┬───────┘
                │ DeleteAsset
                ▼
            (已删除)

状态	含义	可执行操作
`Processing`	处理中，正在拉取源文件并进行内容审核	仅可 `GetAsset` 轮询、`DeleteAsset`
`Active`	审核通过，可用	全量操作；可 `asset://` 引用
`Failed`	审核失败或源文件不可访问	仅可 `DeleteAsset`

8.2 视频任务状态流转

queued ──► running ──► succeeded
               │
               ├──► failed
               └──► cancelled

状态	含义
`queued`	排队中，等待调度
`running`	生成中
`succeeded`	生成成功，`content.video_url` 可用
`failed`	生成失败
`cancelled`	已取消

9. 错误码参考

9.1 网关层错误

网关层错误不包含 ResponseMetadata，直接返回错误信息。

HTTP 状态码	错误信息	触发场景	处理建议
401	`未提供令牌`	请求未携带 `Authorization` 头	检查请求头是否正确设置
401	`无效的令牌`	令牌错误、过期或已被禁用	在控制台确认令牌状态，必要时重新创建
403	`resource does not belong to current user`	访问的资源不属于当前用户（含资源 ID 不存在）	检查资源 ID 与令牌的归属关系

9.2 业务层错误

业务层错误包含完整的 ResponseMetadata，错误信息位于 ResponseMetadata.Error 中。

Error.Code	说明	处理建议
`MissingParameter.<字段名>`	缺少必填参数	根据 Message 补充对应字段
`InvalidParameter.<字段名>`	参数格式或取值不合法	检查参数值是否符合约束
`InvalidActionOrVersion`	Action 名称或 Version 版本号错误	检查 URL 中的 Action 和 Version 参数
`SubscriptionRequired`	未开通所需权益	在控制台完成授权签署

业务层错误响应示例：

{
  "ResponseMetadata": {
    "RequestId": "202606241529096954A62A765732A09755",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "MissingParameter.Name",
      "Message": "The required parameter Name is missing."
    }
  }
}

9.3 重试策略

错误类型	是否可重试	建议
HTTP 5xx	可重试	指数退避，最多 3 ~ 5 次
网络超时	可重试	指数退避，最多 3 ~ 5 次
401 鉴权失败	不可重试	检查令牌配置
403 资源不属当前用户	不可重试	检查资源 ID
`MissingParameter.*`	不可重试	修正请求参数
`InvalidParameter.*`	不可重试	修正请求参数

10. 使用限制

10.1 素材文件规格

图片素材

限制项	要求
格式	jpeg、png、webp、bmp、tiff、gif、heic、heif
文件大小	< 30 MB
宽高比（宽/高）	(0.4, 2.5)
宽高长度	300 ~ 6,000 px

视频素材

限制项	要求
格式	mp4、mov
文件大小	≤ 50 MB
分辨率	480p、720p、1080p
时长	2 ~ 15 秒
宽高比（宽/高）	[0.4, 2.5]
宽高长度	300 ~ 6,000 px
总像素数（宽 × 高）	409,600 ~ 2,086,876
帧率	24 ~ 60 FPS

音频素材

限制项	要求
格式	wav、mp3
文件大小	≤ 15 MB
时长	2 ~ 15 秒

10.2 时效性

项目	有效期	说明
素材下载链接（`URL` 字段）	12 小时	过期后重新调用 `GetAsset` 获取新链接
视频生成结果（`video_url`）	48 小时	对应 `execution_expires_after` 字段

10.3 计费说明

视频生成按 usage.completion_tokens 计费，具体费率请参见DataeyesAI控制台的计费规则页面。
素材库的存储与审核当前不单独计费。

11. 常见问题

Q：素材上传后一直处于 Processing 状态？

A：请检查源 URL 是否可被公网正常访问。若 URL 需要登录认证或有地域访问限制，平台将无法拉取资源，最终状态会变为 Failed。图片资源通常 3 ~ 10 秒内完成处理。

Q：调用接口返回 resource does not belong to current user？

A：该错误表示您尝试访问的资源（素材或素材组）不属于当前 API 令牌所在的账号。请检查：

资源 ID 是否正确；
是否使用了正确账号下的 API 令牌。

素材库的隔离粒度为账号级别：同一账号下的所有 API 令牌（无论属于哪个 Seedance 2.0 模型分组）共享同一套素材库数据；不同账号之间完全隔离。

Q：同一账号下不同分组的 API 令牌能共享素材吗？

A：可以。素材库按账号隔离，同一账号下所有 Seedance 2.0 模型分组的 API 令牌看到的素材组和素材完全一致。使用任意一个令牌创建的素材，其他令牌均可查看和引用。

Q：素材下载链接 URL 字段为空字符串？

A：素材状态为 Processing 时，URL 字段返回空字符串 ""。请等待素材状态变为 Active 后再获取下载链接。

Q：视频生成任务超时仍未完成？

A：视频生成耗时取决于分辨率和时长。720p / 5 秒通常 1 ~ 3 分钟完成；4K 分辨率可能需要 30 分钟以上。

Q：URL 字段返回的下载链接过期了怎么办？

A：素材下载链接有效期为 12 小时，过期后重新调用 GetAsset 接口即可获取新的签名链接。素材本身不会过期，只是临时下载链接有时效限制。

12. 变更记录

版本	日期	变更说明
v1.0	2026-06-24	正式发布。覆盖素材组 5 个接口、素材 5 个接口、视频生成集成、错误码与状态机

Seedance 私域素材库 API

Seedance 私域素材库 API 文档

目录

1. 概述

核心能力

典型场景

2. 接入准备

2.1 服务地址

2.2 获取 API 令牌

2.3 鉴权方式

3. 通用协议

3.1 请求路由

3.2 请求格式

3.3 响应格式

3.4 时间格式

3.5 资源 ID 格式

4. 素材组接口

4.1 创建素材组 CreateAssetGroup

4.2 查询素材组列表 ListAssetGroups

4.3 查询素材组详情 GetAssetGroup

4.4 更新素材组 UpdateAssetGroup

4.5 删除素材组 DeleteAssetGroup

5. 素材接口

5.1 上传素材 CreateAsset

5.2 查询素材列表 ListAssets

5.3 查询素材详情 GetAsset

5.4 更新素材 UpdateAsset

5.5 删除素材 DeleteAsset

6. 在视频生成中引用素材

6.1 提交视频生成任务

6.2 查询视频生成结果

7. 端到端调用示例

8. 素材状态机

8.1 素材状态流转

8.2 视频任务状态流转

9. 错误码参考

9.1 网关层错误

9.2 业务层错误

9.3 重试策略

10. 使用限制

10.1 素材文件规格

10.2 时效性

10.3 计费说明

11. 常见问题

12. 变更记录