视频与素材
素材 Action(火山兼容)
10 个火山引擎兼容的素材与素材组 Action 参考。
这些接口支持下列素材 Action 和字段,使用 TokenLab Bearer 认证及 ResponseMetadata + Result 响应结构。
接口与鉴权
POST https://api.tokenlab.sh/?Action=<ACTION>&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/json也支持 POST /api/v3?Action=<ACTION>&Version=2024-01-01。所有素材 Action 只接受 POST。不接受火山引擎 AK/SK 签名;没有有效 TokenLab Bearer 密钥的请求会返回 401 InvalidCredential。
ProjectName 默认为 default,是已认证组织内真实的隔离边界。创建、列出、读取、更新或删除相关的素材组和素材时,请使用相同的值。
素材组 Action
| Action | 用途 | 请求体 |
|---|---|---|
CreateAssetGroup | 创建虚拟形象素材组 | Name;可选 Description;可选 GroupType: "AIGC";ProjectName |
ListAssetGroups | 列出一个项目内的素材组 | 可选 Filter.GroupIds、Filter.GroupType、Filter.Name;PageNumber、PageSize、SortBy、SortOrder、ProjectName |
GetAssetGroup | 读取单个素材组 | Id、ProjectName |
UpdateAssetGroup | 修改素材组名称或描述 | Id;Name 和/或 Description;ProjectName |
DeleteAssetGroup | 删除素材组及其中的素材 | Id、ProjectName |
CreateAssetGroup 只接受 GroupType: "AIGC"。LivenessFace 组由真人验证成功后创建,不通过此 Action 创建。ListAssetGroups 可以同时筛选 AIGC 和 LivenessFace 组。Name 为 1–64 个字符,Description 最多 300 个字符,比 /v1/videos/assets* REST 接口的限制更短。
创建素材组
curl 'https://api.tokenlab.sh/?Action=CreateAssetGroup&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name":"Product references",
"Description":"Reusable product shots",
"GroupType":"AIGC",
"ProjectName":"default"
}'{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": { "Id": "group-20260720123456-abc12" }
}素材 Action
| Action | 用途 | 请求体 |
|---|---|---|
CreateAsset | 导入一个公开的图片、视频或音频 URL | GroupId、URL、Name、AssetType、ProjectName |
ListAssets | 列出一个项目内的素材 | 可选 Filter.GroupIds、Filter.GroupType、Filter.Statuses、Filter.Name;PageNumber、PageSize、SortBy、SortOrder、ProjectName |
GetAsset | 读取单个素材及其临时 URL | Id、ProjectName |
UpdateAsset | 重命名素材 | Id;可选 Name;ProjectName |
DeleteAsset | 删除单个素材 | Id、ProjectName |
AssetType 支持 Image、Video 和 Audio。目标素材组决定它是普通 AIGC 素材还是已验证的 LivenessFace 素材。
创建素材
curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"GroupId":"group-20260720123456-abc12",
"URL":"https://example.com/reference.png",
"Name":"Front view",
"AssetType":"Image",
"ProjectName":"default"
}'请使用 TokenLab 素材 ID。CreateAsset 在处理完成前返回 Result.Id;轮询 GetAsset,直到 Result.Status 为 Active 或 Failed。ListAssets 还支持 SortBy: "GroupId"。
列表行为
PageNumber 默认是 1;PageSize 默认是 10,最大为 100。SortBy 支持 CreateTime 或 UpdateTime;SortOrder 支持 Desc 或 Asc。
列表响应返回:
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [],
"TotalCount": 0,
"PageNumber": 1,
"PageSize": 10
}
}素材状态为 Active、Processing 和 Failed。GetAsset 和 ListAssets 返回有效期 12 小时的临时 URL;不要把它保存为素材的永久标识,请保存 Id。
返回结果
| Action | Result(主要字段) |
|---|---|
CreateAssetGroup、CreateAsset、UpdateAssetGroup、UpdateAsset | { "Id": "..." } |
DeleteAssetGroup、DeleteAsset | {} |
GetAssetGroup | Id、Name、Description、GroupType、ProjectName、CreateTime、UpdateTime |
GetAsset | Id、GroupId、Name、AssetType、URL、Status、Error(Code 和 Message,素材未失败时为空)、ProjectName、CreateTime、UpdateTime |
时间为 ISO 8601 字符串。ListAssetGroups 和 ListAssets 在 Result.Items 中返回这些对象。
真人素材
导入真人素材之前:
上传到 LivenessFace 组的内容会与已验证的人脸比对。DeleteAssetGroup 不会删除已验证的真人素材组,会返回 409 OperationDenied。
错误
错误保留火山引擎的响应结构,错误码和消息位于 ResponseMetadata.Error。
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing",
"Error": {
"Code": "InvalidParameter",
"Message": "GroupId is required"
}
}
}常见错误码包括 InvalidCredential、InvalidVersion、InvalidParameter、ResourceNotFound、Conflict、OperationDenied、MethodNotAllowed、AccessDenied、FlowLimitExceeded 和 InternalError。HTTP 状态码:请求有误为 400,素材组或素材不存在为 404,冲突为 409,非 POST 方法为 405。
REST 替代方案
TokenLab 的 /v1/videos/assets* REST 接口仍然可用。新的 TokenLab 原生集成可以优先使用其 snake_case 请求体;现有火山引擎客户端无需调整请求结构,即可直接使用本页的 Action。完整的素材生命周期见 Seedance 素材与真人验证。
curl -X POST "https://example.com/api/v3" \ -H "Content-Type: application/json" \ -d '{ "CallbackURL": "http://example.com" }'{ "id": "string"}授权
BearerAuth API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。
位置: header
查询参数
可选值
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"请求头
单次请求的交付策略。覆盖 API 密钥和 Workspace 的默认设置。自动优先尝试 TokenLab Verified,并在输出、请求接受或持久资源创建之前,可能会切换一次至仅限 Official。
可选值
- "auto"
- "verified"
- "official"
请求体
application/json
响应
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json