> ## 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.

# 소재 Action(Volcengine 호환)

> 10개의 Volcengine 호환 소재 및 소재 그룹 Action 레퍼런스입니다.

기존 Volcengine 소재 클라이언트는 Action 이름, `Version=2024-01-01`, PascalCase JSON, 필터, 정렬, 페이지네이션, `ResponseMetadata + Result` envelope을 유지할 수 있습니다. TokenLab에서는 엔드포인트와 인증 방식만 바꿉니다.

## 엔드포인트 및 인증

```text theme={null}
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`; `PageNumber`; `PageSize`; `SortBy`; `SortOrder`; `ProjectName` |
| `GetAssetGroup`    | 그룹 하나 조회       | `Id`; `ProjectName`                                                      |
| `UpdateAssetGroup` | 그룹 이름 또는 설명 변경 | `Id`; `Name`; `Description`; `ProjectName`                               |
| `DeleteAssetGroup` | 그룹과 내부 소재 삭제   | `Id`; `ProjectName`                                                      |

`CreateAssetGroup`은 `AIGC` 그룹만 생성합니다. `LivenessFace` 그룹은 실존 인물 인증 성공 시 생성되며 `ListAssetGroups`는 두 그룹 유형을 모두 필터링할 수 있습니다.

### 소재 그룹 생성

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

## 소재 Action

| Action        | 목표                             | JSON                                                                     |
| ------------- | ------------------------------ | ------------------------------------------------------------------------ |
| `CreateAsset` | 공개 이미지, 비디오 또는 오디오 URL 하나 가져오기 | `GroupId`; `URL`; `Name`; `AssetType`; `ProjectName`                     |
| `ListAssets`  | 프로젝트의 소재 목록 조회                 | `Filter`; `PageNumber`; `PageSize`; `SortBy`; `SortOrder`; `ProjectName` |
| `GetAsset`    | 소재와 임시 URL 조회                  | `Id`; `ProjectName`                                                      |
| `UpdateAsset` | 소재 이름 변경                       | `Id`; `Name`; `ProjectName`                                              |
| `DeleteAsset` | 소재 하나 삭제                       | `Id`; `ProjectName`                                                      |

`AssetType`은 `Image`, `Video`, `Audio`를 지원합니다. 대상 그룹이 일반 `AIGC` 소재인지 인증된 `LivenessFace` 소재인지 결정합니다.

### 소재 생성

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

## 목록 동작

`PageNumber` 기본값은 `1`, `PageSize` 기본값은 `10`이고 최대 `100`입니다. `SortBy`는 `CreateTime` 또는 `UpdateTime`, `SortOrder`는 `Desc` 또는 `Asc`입니다.

소재 상태는 `Active`, `Processing`, `Failed`입니다. `GetAsset`과 `ListAssets`가 반환하는 임시 `URL`은 12시간 동안 유효합니다. 영구 식별자로 `Id`를 저장하세요.

`ListAssetGroups`와 `ListAssets`는 `Result.Items`에 리소스를 반환하며 `TotalCount`, `PageNumber`, `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}
}
```

## 실존 인물 소재

시각 인증 세션을 만들고 H5 인증을 완료한 뒤 결과의 `GroupId`로 `CreateAsset`을 호출합니다. 업로드는 인증된 얼굴과 비교됩니다.

1. [시각 인증 세션 생성](/ko/api-reference/video/create-visual-validation-session)
2. [시각 인증 결과 조회](/ko/api-reference/video/get-visual-validation-result)
3. 반환된 `GroupId`로 `CreateAsset` 호출

## 오류

오류도 Volcengine 응답 envelope을 사용하며 코드와 메시지는 `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`.

## REST 대안

TokenLab의 `/v1/videos/assets*` REST API도 계속 사용할 수 있습니다. 새 통합은 snake\_case REST를 선택할 수 있고 기존 Volcengine 클라이언트는 본문을 바꿀 필요가 없습니다. [Seedance 소재 및 실존 인물 인증](/ko/guides/seedance-materials).