Video y recursos
Acciones de Materiales (Compatibles con Volc)
Referencia para las 10 acciones de materiales y grupos de materiales compatibles con Volcengine.
Estos endpoints admiten las acciones y campos de materiales listados a continuación, utilizando la autenticación Bearer de TokenLab y el sobre ResponseMetadata + Result.
Endpoint y Autenticación
POST https://api.tokenlab.sh/?Action=<ACTION>&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/jsonPOST /api/v3?Action=<ACTION>&Version=2024-01-01 también es compatible. Todas las acciones de materiales son exclusivamente POST. No se aceptan firmas AK/SK de Volcengine; una solicitud sin una clave Bearer de TokenLab válida devuelve 401 InvalidCredential.
ProjectName tiene como valor predeterminado default y es un límite de aislamiento real dentro de la organización autenticada. Utilice el mismo valor al crear, listar, leer, actualizar o eliminar grupos y activos relacionados.
Acciones de Grupos de Materiales
| Acción | Propósito | Cuerpo de la solicitud |
|---|---|---|
CreateAssetGroup | Crear un grupo de materiales de avatar virtual | Name; Description opcional; GroupType: "AIGC" opcional; ProjectName |
ListAssetGroups | Listar grupos en un proyecto | Filter.GroupIds, Filter.GroupType, Filter.Name opcionales; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAssetGroup | Leer un grupo | Id, ProjectName |
UpdateAssetGroup | Cambiar el nombre o la descripción del grupo | Id; Name y/o Description; ProjectName |
DeleteAssetGroup | Eliminar un grupo y sus activos | Id, ProjectName |
CreateAssetGroup solo acepta GroupType: "AIGC". Un grupo LivenessFace se crea mediante una verificación de persona real exitosa, no mediante esta acción. ListAssetGroups puede filtrar grupos tanto AIGC como LivenessFace. Name tiene de 1 a 64 caracteres y Description hasta 300, lo cual es más corto que los límites de los endpoints REST /v1/videos/assets*.
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" }
}Acciones de Activos de Materiales
| Acción | Propósito | Cuerpo de la solicitud |
|---|---|---|
CreateAsset | Importar una URL pública de imagen, video o audio | GroupId, URL, Name, AssetType, ProjectName |
ListAssets | Listar activos en un proyecto | Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name opcionales; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAsset | Leer un activo y su URL temporal | Id, ProjectName |
UpdateAsset | Renombrar un activo | Id; Name opcional; ProjectName |
DeleteAsset | Eliminar un activo | Id, ProjectName |
AssetType acepta Image, Video o Audio. El grupo de destino determina si el activo es un material AIGC normal o un material LivenessFace verificado.
Crear un Activo
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"
}'Utilice los IDs de materiales de TokenLab. CreateAsset devuelve Result.Id antes de que finalice el procesamiento; realice sondeos con GetAsset hasta que Result.Status sea Active o Failed. ListAssets también acepta SortBy: "GroupId".
Comportamiento de Listado
PageNumber tiene como valor predeterminado 1; PageSize tiene como valor predeterminado 10 y acepta hasta 100. SortBy acepta CreateTime o UpdateTime; SortOrder acepta Desc o Asc.
Las respuestas de listado devuelven:
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [],
"TotalCount": 0,
"PageNumber": 1,
"PageSize": 10
}
}Los valores de estado del activo son Active, Processing y Failed. GetAsset y ListAssets devuelven una URL temporal válida por 12 horas; no la almacene como la identidad permanente del activo. Almacene el Id en su lugar.
Resultados
| Acción | Result (campos principales) |
|---|---|
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset | { "Id": "..." } |
DeleteAssetGroup, DeleteAsset | {} |
GetAssetGroup | Id, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime |
GetAsset | Id, GroupId, Name, AssetType, URL, Status, Error (Code y Message, vacío a menos que el activo haya fallado), ProjectName, CreateTime, UpdateTime |
Los tiempos son cadenas ISO 8601. ListAssetGroups y ListAssets devuelven estos objetos en Result.Items.
Materiales de Persona Real
Antes de importar un activo para una persona real:
- Llame a Crear sesión de validación visual.
- Complete el flujo de verificación H5.
- Llame a Obtener resultado de validación visual hasta que devuelva
Result.GroupId. - Llame a
CreateAssetcon ese ID de grupo verificado.
Las cargas a un grupo LivenessFace se verifican contra el rostro verificado. DeleteAssetGroup no elimina un grupo de persona real verificado; devuelve 409 OperationDenied.
Errores
Los errores mantienen el sobre de respuesta de Volcengine y colocan el código y el mensaje bajo ResponseMetadata.Error.
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing",
"Error": {
"Code": "InvalidParameter",
"Message": "GroupId is required"
}
}
}Los códigos comunes incluyen InvalidCredential, InvalidVersion, InvalidParameter, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded e InternalError. El estado HTTP es 400 para solicitudes incorrectas, 404 para un grupo o activo faltante, 409 para conflictos y 405 para un método que no es POST.
Alternativa REST
Los endpoints REST /v1/videos/assets* de TokenLab siguen estando disponibles. Las nuevas integraciones nativas de TokenLab pueden preferir sus cuerpos en snake_case; los clientes existentes de Volcengine pueden usar las acciones en esta página sin necesidad de modificar las solicitudes. Consulte Materiales de Seedance y Verificación de Persona Real para conocer el ciclo de vida completo del activo.
curl -X POST "https://example.com/api/v3" \ -H "Content-Type: application/json" \ -d '{ "CallbackURL": "http://example.com" }'{ "id": "string"}Autorización
BearerAuth Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.
Ubicación: header
Parámetros de consulta
Valores permitidos
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"Encabezados
Política de entrega por solicitud. Sustituye los valores predeterminados de la API key y del Workspace. Auto intenta primero con TokenLab Verified y puede cambiar una vez a Official solo antes de la salida, la aceptación de la solicitud o la creación de recursos persistentes.
Valores permitidos
- "auto"
- "verified"
- "official"
Cuerpo de la solicitud
application/json
Respuesta
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json