Video y recursos

Acciones de Materiales (Compatibles con Volc)

Referencia para las 10 acciones de materiales y grupos de materiales compatibles con Volcengine.

POST
/api/v3

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/json

POST /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ónPropósitoCuerpo de la solicitud
CreateAssetGroupCrear un grupo de materiales de avatar virtualName; Description opcional; GroupType: "AIGC" opcional; ProjectName
ListAssetGroupsListar grupos en un proyectoFilter.GroupIds, Filter.GroupType, Filter.Name opcionales; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroupLeer un grupoId, ProjectName
UpdateAssetGroupCambiar el nombre o la descripción del grupoId; Name y/o Description; ProjectName
DeleteAssetGroupEliminar un grupo y sus activosId, 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ónPropósitoCuerpo de la solicitud
CreateAssetImportar una URL pública de imagen, video o audioGroupId, URL, Name, AssetType, ProjectName
ListAssetsListar activos en un proyectoFilter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name opcionales; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetLeer un activo y su URL temporalId, ProjectName
UpdateAssetRenombrar un activoId; Name opcional; ProjectName
DeleteAssetEliminar un activoId, 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ónResult (campos principales)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, 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:

  1. Llame a Crear sesión de validación visual.
  2. Complete el flujo de verificación H5.
  3. Llame a Obtener resultado de validación visual hasta que devuelva Result.GroupId.
  4. Llame a CreateAsset con 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
AuthorizationBearer <token>

Autenticación con API Key. Cree o gestione API keys en Dashboard > API > API Keys.

Ubicación: header

Parámetros de consulta

Action?string

Valores permitidos

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

Encabezados

X-TokenLab-Delivery-Policy?string

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