Actions de materiales (compatibles con Volcengine)

Un cliente de materiales Volcengine puede conservar nombres de Action, Version=2024-01-01, JSON PascalCase, filtros, orden, paginación y el sobre ResponseMetadata + Result. TokenLab solo cambia endpoint y autenticación.

Endpoint y autenticación

POST https://api.tokenlab.sh/?Action=<ACTION>&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/json

También se admite POST /api/v3?Action=<ACTION>&Version=2024-01-01. Todas las Actions de materiales son solo POST. Una solicitud con únicamente firma AK/SK devuelve 401 InvalidCredential. ProjectName usa default por defecto y es una frontera real de aislamiento dentro de la organización autenticada. Usa el mismo valor en solicitudes relacionadas.

Actions de grupos

Action	Objetivo	JSON
`CreateAssetGroup`	Crear un grupo de materiales normal	`Name`; `Description`; `GroupType: "AIGC"`; `ProjectName`
`ListAssetGroups`	Listar grupos de un proyecto	`Filter`; `PageNumber`; `PageSize`; `SortBy`; `SortOrder`; `ProjectName`
`GetAssetGroup`	Obtener un grupo	`Id`; `ProjectName`
`UpdateAssetGroup`	Cambiar nombre o descripción	`Id`; `Name`; `Description`; `ProjectName`
`DeleteAssetGroup`	Eliminar grupo y materiales	`Id`; `ProjectName`

CreateAssetGroup solo crea grupos AIGC. Un grupo LivenessFace se crea tras verificar correctamente a la persona; ListAssetGroups puede filtrar ambos tipos.

Crear un grupo

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

Actions de materiales

Action	Objetivo	JSON
`CreateAsset`	Importar una URL pública de imagen, video o audio	`GroupId`; `URL`; `Name`; `AssetType`; `ProjectName`
`ListAssets`	Listar materiales de un proyecto	`Filter`; `PageNumber`; `PageSize`; `SortBy`; `SortOrder`; `ProjectName`
`GetAsset`	Obtener material y URL temporal	`Id`; `ProjectName`
`UpdateAsset`	Renombrar material	`Id`; `Name`; `ProjectName`
`DeleteAsset`	Eliminar un material	`Id`; `ProjectName`

AssetType admite Image, Video y Audio. El grupo de destino determina si es un material AIGC normal o LivenessFace verificado.

Crear un material

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

Comportamiento de listas

PageNumber usa 1 por defecto; PageSize usa 10 y admite hasta 100. SortBy admite CreateTime o UpdateTime; SortOrder admite Desc o Asc. Los estados son Active, Processing y Failed. Las URL temporales de GetAsset y ListAssets duran 12 horas. Guarda Id como identidad permanente. ListAssetGroups y ListAssets devuelven recursos en Result.Items, junto con TotalCount, PageNumber y PageSize.

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

Materiales de personas reales

Crea una sesión de verificación visual, completa H5, obtiene GroupId y llama a CreateAsset con ese grupo. Las cargas se comparan con el rostro verificado.

Crear sesión de verificación visual
Obtener resultado de verificación visual
Llamar a CreateAsset con el GroupId devuelto

Errores

Los errores mantienen el sobre Volcengine; código y mensaje están en 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, MethodNotAllowed, InternalError.

Alternativa REST

Los endpoints REST /v1/videos/assets* siguen disponibles. Las nuevas integraciones pueden elegir REST snake_case; los clientes Volcengine no necesitan reformatear sus cuerpos. Materiales de Seedance y verificación de personas.

Obtener resultado de validación visual Crear grupo de activos de material

Base

Texto

Archivos y lotes

Imágenes

Audio y tiempo real

Música

Video y recursos

Worlds

3D

Trabajos asíncronos

Gemini nativo

Administración

Actions de materiales (compatibles con Volcengine)

Endpoint y autenticación

Actions de grupos

Crear un grupo

Actions de materiales

Crear un material

Comportamiento de listas

Materiales de personas reales

Errores

Alternativa REST

​Endpoint y autenticación

​Actions de grupos

​Crear un grupo

​Actions de materiales

​Crear un material

​Comportamiento de listas

​Materiales de personas reales

​Errores

​Alternativa REST

Endpoint y autenticación

Actions de grupos

Crear un grupo

Actions de materiales

Crear un material

Comportamiento de listas

Materiales de personas reales

Errores

Alternativa REST