视频与素材

素材 Action(火山兼容)

10 个火山引擎兼容的素材与素材组 Action 参考。

POST
/api/v3

这些接口支持下列素材 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导入一个公开的图片、视频或音频 URLGroupId、URL、Name、AssetType、ProjectName
ListAssets列出一个项目内的素材可选 Filter.GroupIds、Filter.GroupType、Filter.Statuses、Filter.Name;PageNumber、PageSize、SortBy、SortOrder、ProjectName
GetAsset读取单个素材及其临时 URLId、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。

返回结果

ActionResult(主要字段)
CreateAssetGroup、CreateAsset、UpdateAssetGroup、UpdateAsset{ "Id": "..." }
DeleteAssetGroup、DeleteAsset{}
GetAssetGroupId、Name、Description、GroupType、ProjectName、CreateTime、UpdateTime
GetAssetId、GroupId、Name、AssetType、URL、Status、Error(Code 和 Message,素材未失败时为空)、ProjectName、CreateTime、UpdateTime

时间为 ISO 8601 字符串。ListAssetGroups 和 ListAssets 在 Result.Items 中返回这些对象。

真人素材

导入真人素材之前:

  1. 调用创建视觉验证会话。
  2. 完成 H5 验证流程。
  3. 调用获取视觉验证结果,直到返回 Result.GroupId。
  4. 使用该已验证的素材组 ID 调用 CreateAsset。

上传到 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
AuthorizationBearer <token>

API Key 身份验证。在 Dashboard > API > API Keys 中创建或管理 API Key。

位置: header

查询参数

Action?string

可选值

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
默认值"2024-01-01"

请求头

X-TokenLab-Delivery-Policy?string

单次请求的交付策略。覆盖 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