> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Actions de materiales (compatibles con Volcengine)

> Referencia de las diez Actions compatibles con Volcengine para materiales y grupos.

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

```text theme={null}
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

```bash theme={null}
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"}'
```

```json theme={null}
{
  "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

```bash theme={null}
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`.

```json theme={null}
{
  "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.

1. [Crear sesión de verificación visual](/es/api-reference/video/create-visual-validation-session)
2. [Obtener resultado de verificación visual](/es/api-reference/video/get-visual-validation-result)
3. Llamar a `CreateAsset` con el `GroupId` devuelto

## Errores

Los errores mantienen el sobre Volcengine; código y mensaje están en `ResponseMetadata.Error`.

```json theme={null}
{
  "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](/es/guides/seedance-materials).