TokenLab

비디오 및 자료

Material Actions (Volc 호환)

10가지 Volcengine 호환 Material 및 Material-Group Action에 대한 참조 문서입니다.

POST
/api/v3

이 엔드포인트들은 TokenLab Bearer 인증과 ResponseMetadata + Result 봉투(envelope) 형식을 사용하여 아래 나열된 Material Action 및 필드를 지원합니다.

엔드포인트 및 인증

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 또한 지원됩니다. 모든 Material Action은 POST 전용입니다. Volcengine AK/SK 서명은 허용되지 않으며, 유효한 TokenLab Bearer 키가 없는 요청은 401 InvalidCredential을 반환합니다.

ProjectName은 기본값이 default이며, 인증된 조직 내의 실제 격리 경계입니다. 관련 그룹 및 에셋을 생성, 나열, 읽기, 업데이트 또는 삭제할 때 동일한 값을 사용하십시오.

Material-Group Actions

Action목적요청 본문
CreateAssetGroup가상 아바타 Material 그룹 생성Name; 선택 사항 Description; 선택 사항 GroupType: "AIGC"; ProjectName
ListAssetGroups프로젝트 내 그룹 나열선택 사항 Filter.GroupIds, Filter.GroupType, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroup단일 그룹 읽기Id, ProjectName
UpdateAssetGroup그룹 이름 또는 설명 변경Id; Name 및/또는 Description; ProjectName
DeleteAssetGroup그룹 및 해당 에셋 삭제Id, ProjectName

CreateAssetGroup은 GroupType: "AIGC"만 허용합니다. LivenessFace 그룹은 이 Action이 아닌 성공적인 실인물 인증을 통해 생성됩니다. ListAssetGroups는 AIGC 및 LivenessFace 그룹을 모두 필터링할 수 있습니다. Name은 1~64자, Description은 최대 300자까지 가능하며, 이는 /v1/videos/assets* REST 엔드포인트의 제한보다 짧습니다.

그룹 생성

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

Material-Asset Actions

Action목적요청 본문
CreateAsset공개 이미지, 비디오 또는 오디오 URL 가져오기GroupId, URL, Name, AssetType, ProjectName
ListAssets프로젝트 내 에셋 나열선택 사항 Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAsset단일 에셋 및 임시 URL 읽기Id, ProjectName
UpdateAsset에셋 이름 변경Id; 선택 사항 Name; ProjectName
DeleteAsset단일 에셋 삭제Id, ProjectName

AssetType은 Image, Video 또는 Audio를 허용합니다. 대상 그룹에 따라 에셋이 일반 AIGC Material인지, 인증된 LivenessFace Material인지 결정됩니다.

에셋 생성

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

TokenLab Material ID를 사용하십시오. CreateAsset은 처리가 완료되기 전에 Result.Id를 반환합니다. Result.Status가 Active 또는 Failed가 될 때까지 GetAsset을 폴링하십시오. ListAssets는 SortBy: "GroupId"도 허용합니다.

나열 동작

PageNumber의 기본값은 1이며, PageSize의 기본값은 10이고 최대 100까지 허용됩니다. SortBy는 CreateTime 또는 UpdateTime을 허용하며, SortOrder는 Desc 또는 Asc를 허용합니다.

나열 응답은 다음을 반환합니다:

{
  "ResponseMetadata": {
    "RequestId": "req-id",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [],
    "TotalCount": 0,
    "PageNumber": 1,
    "PageSize": 10
  }
}

에셋 상태 값은 Active, Processing, Failed입니다. GetAsset 및 ListAssets는 12시간 동안 유효한 임시 URL을 반환합니다. 이를 영구적인 에셋 식별자로 저장하지 마십시오. 대신 Id를 저장하십시오.

결과

ActionResult (주요 필드)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code 및 Message, 에셋 실패 시에만 표시), ProjectName, CreateTime, UpdateTime

시간은 ISO 8601 문자열입니다. ListAssetGroups 및 ListAssets는 Result.Items 내에 이러한 객체들을 반환합니다.

실인물 Material

실인물에 대한 에셋을 가져오기 전에:

  1. 시각적 검증 세션 생성을 호출합니다.
  2. H5 인증 절차를 완료합니다.
  3. Result.GroupId가 반환될 때까지 시각적 검증 결과 가져오기를 호출합니다.
  4. 해당 인증된 그룹 ID로 CreateAsset을 호출합니다.

LivenessFace 그룹에 대한 업로드는 인증된 얼굴과 대조하여 확인됩니다. DeleteAssetGroup은 인증된 실인물 그룹을 삭제하지 않으며, 409 OperationDenied를 반환합니다.

오류

오류는 Volcengine 응답 봉투를 유지하며 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, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded, InternalError가 있습니다. HTTP 상태 코드는 잘못된 요청의 경우 400, 그룹 또는 에셋이 없는 경우 404, 충돌의 경우 409, POST가 아닌 메서드의 경우 405입니다.

REST 대안

TokenLab의 /v1/videos/assets* REST 엔드포인트를 계속 사용할 수 있습니다. 새로운 TokenLab 네이티브 통합은 snake_case 본문을 선호할 수 있으나, 기존 Volcengine 클라이언트는 요청을 재구성할 필요 없이 이 페이지의 Action을 사용할 수 있습니다. 전체 에셋 수명 주기에 대해서는 Seedance 소재 및 실존 인물 인증을 참조하십시오.

curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

쿼리 매개변수

Action?string

허용 값

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

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

  • "auto"
  • "verified"
  • "official"

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json