Seedance 소재 및 실존 인물 인증

Seedance 소재는 조직 범위에서 재사용할 수 있는 이미지, 비디오 또는 오디오 참조입니다. 먼저 워크플로를 선택하세요. 일반 아바타 소재와 인증된 실존 인물 소재는 생성 경로가 다릅니다.

소재 워크플로 선택

목표	필수 흐름
일회성 이미지 URL 사용	비디오 요청에 URL을 직접 보내면 호환 모델이 자동으로 소재 준비
아바타, 제품 또는 스타일 재사용	`aigc_avatar` 그룹과 소재를 만들고 `ACTIVE`까지 기다린 뒤 소재 ID 사용
실존 인물 재사용	시각 인증을 완료하고 `GroupId`로 소재를 만든 뒤 `ACTIVE`까지 기다려 소재 ID 사용
Volcengine 소재 클라이언트 이전	Action 형식을 유지하고 Volcengine 호환 소재 참조 사용: 소재 Action(Volcengine 호환)

소재 개념

Seedance 소재는 비디오 생성 중에 나중에 선택할 수 있는 재사용 가능한 조직 범위의 참조입니다.

개념	공개 필드	의미
소재 그룹	`group_id`	관련 Seedance 소재를 소유하는 TokenLab 그룹입니다. 소재 업로드 또는 목록 조회 시 사용합니다.
소재 에셋	`id`	업로드된 이미지, 비디오 또는 오디오 파일 하나입니다. 에셋이 `ACTIVE` 상태가 된 후 이 값을 `material_asset_id`로 사용하세요.
가상 아바타 소재 그룹	`library_type: "aigc_avatar"`	실존 인물 확인이 필요 없는 가상 인물, 아바타, 제품, 스타일 및 기타 재사용 가능한 참조용입니다.
실존 인물 소재 그룹	`library_type: "liveness_face"`	실존 인물 소재 확인을 통해 생성됩니다. 하나의 그룹은 한 명의 인증된 실존 인물을 나타냅니다.

group_id와 소재 에셋 id를 구분해서 사용하세요. group_id는 업로드 정리용이며, 소재 에셋 id는 비디오 생성용입니다. 비디오 요청 시 Seedance material asset not found or not accessible 오류가 반환되면, group_id가 아닌 소재 에셋 id를 전달했는지, 해당 에셋이 동일한 조직에 속해 있는지, 삭제되지 않았는지, 그리고 status: "ACTIVE" 상태인지 확인하세요.

자동 이미지 소재

선택한 Seedance 모델이 TokenLab 소재 라이브러리를 사용할 수 있으면 image, image_url, image_urls, reference_images, start_image, end_image에 이미지 URL 또는 지원되는 인라인 data URL을 직접 보낼 수 있습니다. TokenLab은 해당 이미지를 조직의 기본 가상 아바타 소재 그룹으로 가져오고 첫 프레임, 마지막 프레임, 참조 이미지 역할을 유지합니다. 소재가 60초 안에 ACTIVE가 되면 같은 요청에서 생성이 계속됩니다. 준비가 끝나지 않으면 API는 auto_material_asset_ids가 포함된 409 seedance_material_preparing을 반환합니다. 해당 소재를 조회해 ACTIVE가 된 후 material_asset_id 또는 material_asset_ids로 다시 시도하세요. 선택한 모델이 소재 라이브러리를 사용할 수 없으면 일반 이미지 URL 또는 data URL은 일반 이미지 경로로 처리되고, 명시적 소재 ID는 재시도 가능한 소재 가용성 오류로 안전하게 실패합니다. 기존 가상 아바타 소재 ID와 실사 인물 소재 ID는 그대로 사용되며 다시 가져오지 않습니다.

실존 인물 소재 확인

실존 인물을 재사용 가능한 Seedance 참조로 사용하기 전에 동의 및 얼굴 확인이 필요한 경우 실존 인물 소재 확인을 사용하세요.

CallbackURL을 전달하여 시각 인증 세션 생성을 호출하고 반환된 Result.BytedToken을 저장합니다.
인증 대상자가 Result.H5Link를 열도록 합니다. 특정 언어가 필요하면 H5 링크에 lng를 추가합니다.
H5 흐름이 완료되면 브라우저가 bytedToken, resultCode 등의 공식 쿼리 이름과 함께 Result.CallbackURL을 엽니다.
BytedToken으로 시각 인증 결과 조회를 폴링하여 Result.GroupId가 반환될 때까지 기다립니다.
GroupId를 저장하고 liveness_face 자료 생성 시 group_id로 사용합니다.

BytedToken은 30분 동안 유효합니다. 두 Action 요청에서 같은 ProjectName을 사용하십시오. 인증은 Authorization: Bearer <TOKENLAB_API_KEY>를 사용하며 Volc AK/SK 서명은 허용되지 않습니다. 선택 사항: 테스트 콘솔을 사용하여 요청 및 콜백 흐름을 확인하고, 소재 그룹을 검사하며, 확인 기록을 검토하세요. 프로덕션 통합 시에는 API를 직접 호출해야 합니다.

소재 그룹 생성

aigc_avatar 그룹의 경우 머티리얼 에셋 그룹 생성을 사용하세요. 새로운 실존 인물 그룹은 인증된 인물과 소재 그룹이 연결된 상태를 유지하도록 확인 흐름을 통해 생성됩니다. 그룹이 생성된 후 관리하려면 머티리얼 에셋 그룹 목록 조회, 머티리얼 에셋 그룹 가져오기, 머티리얼 에셋 그룹 업데이트 및 머티리얼 에셋 그룹 삭제을 사용하세요. 소재 그룹을 삭제하면 그 안에 포함된 TokenLab 소재도 함께 삭제되며, 이는 되돌릴 수 없습니다. 현재 권한 상태가 허용하지 않아 TokenLab 소재 라이브러리가 삭제를 완료할 수 없는 경우, TokenLab은 중립적인 소재 라이브러리 오류를 반환합니다.

소재 업로드

머티리얼 에셋 생성을 사용하여 공개적으로 접근 가능한 소스 URL을 한 번에 하나씩 가져옵니다. aigc_avatar의 경우 group_id는 선택 사항이며, TokenLab은 조직 기본 가상 아바타 그룹을 사용하거나 생성합니다. liveness_face의 경우 group_id가 필수이며, 시각 인증 결과 조회에서 반환된 그룹이어야 합니다.

유형	지원되는 입력
이미지	`jpeg`, `png`, `webp`, `bmp`, `tiff`, `gif`, `heic`, `heif`; 종횡비 `(0.4, 2.5)`; 너비 및 높이 `(300, 6000)` px; 30 MB 미만.
비디오	`mp4`, `mov`; `480p`, `720p` 또는 `1080p`; 2-15초; 종횡비 `[0.4, 2.5]`; 너비 및 높이 `[300, 6000]` px; 총 픽셀 수 409600 ~ 2068676; 최대 200 MB; 24-60 FPS.
오디오	`aac`, `wav`, `mp3`; 2-15초; 최대 15 MB.

소재 수집은 비동기식입니다. status가 ACTIVE가 될 때까지 머티리얼 에셋 가져오기을 폴링하세요. 성공적인 HTTP 응답은 요청이 수락되었음을 의미할 뿐이므로, 항상 비즈니스 상태를 읽어야 합니다. 상태가 FAILED인 경우 error_message를 검사하고, 원본 소재를 수정한 후 새 에셋을 생성하세요. 소재 생성 요청에서 asset_url은 가져오기 원본만 의미합니다. TokenLab은 소재 에셋 id를 반환합니다. 생성 시 원본 URL 대신 이 id를 사용하십시오. TokenLab은 소재 또는 해당 소재 그룹을 삭제할 때까지 조직 소재 라이브러리에 소재를 보관합니다. 실존 인물 소재 그룹의 경우, 하나의 그룹은 한 명의 실존 인물과 매핑됩니다. 업로드는 인증된 얼굴과 대조하여 확인됩니다. 여러 얼굴이 포함되어 있거나 인증된 인물과 일치하지 않는 얼굴이 포함된 에셋은 실패할 수 있습니다. 최상의 결과를 얻으려면 전신 정면 참조 이미지와 얼굴이 명확하게 보이는 정면 클로즈업 이미지를 모두 업로드하세요.

비디오 생성에서 소재 사용

에셋이 ACTIVE 상태가 된 후, 비디오 생성를 호출할 때 반환된 TokenLab 에셋 id를 material_asset_id로 전달하거나 material_asset_ids에 포함하세요. 소재 에셋은 Seedance 참조 제한에 포함됩니다.

REST 또는 Volcengine Action

TokenLab 네이티브 통합은 snake_case /v1/videos/assets* REST API를 계속 사용할 수 있습니다. 기존 Volcengine 클라이언트는 PascalCase 본문을 유지하고 Volcengine 호환 소재 Action을 사용할 수 있습니다. 두 방식은 같은 조직 및 프로젝트 범위 소재 데이터를 조작합니다.

API 예시

가상 아바타 그룹을 생성하고, 이미지를 업로드하고, 활성화될 때까지 폴링한 다음, 비디오 요청에서 소재 에셋 ID를 사용합니다.

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

실제 인물 자료 그룹의 경우 자료 업로드 전에 시각 인증 세션을 생성하고 결과를 조회합니다.

curl 'https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'

완전한 실존 인물 Action 흐름

인증 결과가 반환한 GroupId를 CreateAsset에 전달합니다.

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-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

GetAsset을 폴링하여 상태가 Active가 되면 반환된 소재 ID를 비디오 생성에 사용합니다.

시작하기

핵심 가이드

미디어 가이드

Seedance 소재 및 실존 인물 인증

소재 워크플로 선택

소재 개념

자동 이미지 소재

실존 인물 소재 확인

소재 그룹 생성

소재 업로드

비디오 생성에서 소재 사용

REST 또는 Volcengine Action

API 예시

완전한 실존 인물 Action 흐름

​소재 워크플로 선택

​소재 개념

​자동 이미지 소재

​실존 인물 소재 확인

​소재 그룹 생성

​소재 업로드

​비디오 생성에서 소재 사용

​REST 또는 Volcengine Action

​API 예시

​완전한 실존 인물 Action 흐름

소재 워크플로 선택

소재 개념

자동 이미지 소재

실존 인물 소재 확인

소재 그룹 생성

소재 업로드

비디오 생성에서 소재 사용

REST 또는 Volcengine Action

API 예시

완전한 실존 인물 Action 흐름