소재 Action(Volcengine 호환)

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

엔드포인트 및 인증

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는 두 그룹 유형을 모두 필터링할 수 있습니다.

소재 그룹 생성

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

소재 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 소재인지 결정합니다.

소재 생성

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도 함께 제공합니다.

{
  "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을 호출합니다. 업로드는 인증된 얼굴과 비교됩니다.

시각 인증 세션 생성
시각 인증 결과 조회
반환된 GroupId로 CreateAsset 호출

오류

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

REST 대안

TokenLab의 /v1/videos/assets* REST API도 계속 사용할 수 있습니다. 새 통합은 snake_case REST를 선택할 수 있고 기존 Volcengine 클라이언트는 본문을 바꿀 필요가 없습니다. Seedance 소재 및 실존 인물 인증.

핵심

텍스트

파일 및 배치

이미지

오디오 및 실시간

음악

비디오 및 자료

Worlds

3D

비동기 작업

Gemini 네이티브

관리

소재 Action(Volcengine 호환)

엔드포인트 및 인증

소재 그룹 Action

소재 그룹 생성

소재 Action

소재 생성

목록 동작

실존 인물 소재

오류

REST 대안

​엔드포인트 및 인증

​소재 그룹 Action

​소재 그룹 생성

​소재 Action

​소재 생성

​목록 동작

​실존 인물 소재

​오류

​REST 대안

엔드포인트 및 인증

소재 그룹 Action

소재 그룹 생성

소재 Action

소재 생성

목록 동작

실존 인물 소재

오류

REST 대안