TokenLab
获取 API 密钥
文档API 参考集成

视频与素材

素材 Action（火山兼容）

通过火山兼容 Action 管理 Seedance 素材和素材组。

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 签名的请求会返回 401 InvalidCredential。

ProjectName 默认为 default。同一组素材的创建、查询、更新和删除请求需要使用相同的值。

素材组 Action

Action目标JSON
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 只能创建 AIGC 组。LivenessFace 组必须由真人验证成功后创建；ListAssetGroups 可以筛选两种组。

创建素材组

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目标JSON
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 素材。

请使用 TokenLab 素材 ID。CreateAsset 在处理完成前返回 Result.Id；轮询 GetAsset，直到 Result.Status 为 Active 或 Failed。ListAssets 还支持 SortBy: "GroupId"。

创建素材

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"}'

列表行为

PageNumber 默认是 1，PageSize 默认是 10 且最大为 100。SortBy 支持 CreateTime 或 UpdateTime；SortOrder 支持 Desc 或 Asc。

素材状态为 Active、Processing 或 Failed。GetAsset 和 ListAssets 返回有效期 12 小时的临时 URL；请保存 Id，不要把 URL 当成永久标识。

ListAssetGroups 和 ListAssets 通过 Result.Items 返回资源，并同时返回 TotalCount、PageNumber 和 PageSize。

{
  "ResponseMetadata": {
    "RequestId": "req-id",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {"Items":[],"TotalCount":0,"PageNumber":1,"PageSize":10}
}

真人素材

先创建视觉验证会话并完成 H5 验证，再获取验证结果返回的 GroupId，最后用该组调用 CreateAsset。上传内容会与已验证的人脸比对。

  1. 创建视觉验证会话
  2. 获取视觉验证结果
  3. 使用返回的 GroupId 调用 CreateAsset

错误

错误码和消息位于 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, NotFound, Conflict, OperationDenied, MethodNotAllowed, InternalError.

REST 接口

也可以使用 snake_case 的 /v1/videos/assets* REST 接口。完整用法见 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

获取视觉验证结果

上一页

创建素材组

下一页