Seedance 소재 및 실존 인물 인증

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

소재 워크플로 선택Copy Anchor Link

소재 개념Copy Anchor Link

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

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

소재 보관 기간Copy Anchor Link

TokenLab은 소재 에셋 또는 해당 그룹을 삭제할 때까지 모든 소재 에셋을 보관합니다. TokenLab 쪽에서는 비활성을 이유로 정리하지 않습니다.

업스트림 Seedance 제공자는 30일 동안 사용되지 않은 에셋의 자체 작업용 사본을 삭제할 수 있습니다. 이로 인해 에셋이 삭제되거나 ID가 바뀌지는 않습니다. 다음에 생성 요청에서 사용하면 TokenLab이 저장된 원본으로 새 업스트림 사본을 자동으로 준비합니다.

• 정리 후 첫 생성은 새 사본을 준비하는 동안 조금 더 오래 걸릴 수 있습니다. 아직 준비되지 않았다면 요청이 seedance_material_preparing을 반환하므로 잠시 후 다시 시도하세요.
• 에셋 또는 그룹 삭제는 영구적이며 되돌릴 수 없습니다.

이미지 URL과 재사용 소재Copy Anchor Link

선택한 모델이 지원하는 이미지 필드에 공개 HTTP(S) URL 또는 지원되는 data URL을 넣을 수 있습니다. 일반 미디어 입력으로 처리되며 재사용 소재 ID를 자동으로 만들지 않습니다.

재사용하려면 소재 API로 에셋을 만들고 ACTIVE를 기다린 뒤 material_asset_id, material_asset_ids 또는 지원 미디어 필드의 asset://<id>를 사용하세요. 첫 프레임, 마지막 프레임, 참조 이미지의 역할을 유지하세요.

명시한 소재가 준비 중이면 POST /v1/videos/generations가 409 seedance_material_preparing과 inactive_asset_ids를 반환합니다. 소재가 ACTIVE가 될 때까지 조회한 뒤 같은 ID로 재시도하세요. FAILED라면 먼저 error_message에 따라 수정하거나 다시 가져오세요.

실존 인물 소재 확인Copy Anchor Link

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

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

BytedToken은 30분 동안 유효합니다. 두 Action 요청에서 같은 ProjectName을 사용하십시오. 인증은 Authorization: Bearer <TOKENLAB_API_KEY>를 사용하며 Volc AK/SK 서명은 허용되지 않습니다.

생성 직후 반환된 H5Link를 여세요. 토큰 유효 기간 중 언제든 검증 페이지를 처음 열 수 있다는 뜻은 아닙니다.

선택 사항: 테스트 콘솔을 사용하여 요청 및 콜백 흐름을 확인하고, 소재 그룹을 검사하며, 확인 기록을 검토하세요. 프로덕션 통합 시에는 API를 직접 호출해야 합니다.

소재 그룹 생성Copy Anchor Link

aigc_avatar 그룹의 경우 머티리얼 에셋 그룹 생성을 사용하세요. 새로운 실존 인물 그룹은 인증된 인물과 소재 그룹이 연결된 상태를 유지하도록 확인 흐름을 통해 생성됩니다.

그룹이 생성된 후 관리하려면 머티리얼 에셋 그룹 목록 조회, 머티리얼 에셋 그룹 가져오기, 머티리얼 에셋 그룹 업데이트 및 머티리얼 에셋 그룹 삭제을 사용하세요.

소재 그룹을 삭제하면 그 안에 포함된 TokenLab 소재도 함께 삭제되며, 이는 되돌릴 수 없습니다. 현재 권한 상태가 허용하지 않아 TokenLab 소재 라이브러리가 삭제를 완료할 수 없는 경우, TokenLab은 중립적인 소재 라이브러리 오류를 반환합니다.

소재 업로드Copy Anchor Link

머티리얼 에셋 생성을 사용하여 공개적으로 접근 가능한 소스 URL을 한 번에 하나씩 가져옵니다.

aigc_avatar의 경우 group_id는 선택 사항이며, TokenLab은 조직 기본 가상 아바타 그룹을 사용하거나 생성합니다. liveness_face의 경우 group_id가 필수이며, 시각 인증 결과 조회에서 반환된 그룹이어야 합니다.

표는 파일 가져오기 제한입니다. 가져오기 요청 성공이 미디어나 실존 인물 검증 통과를 보장하지는 않습니다. ACTIVE를 기다리고 FAILED이면 error_message에 따라 원본을 수정한 뒤 다시 가져오세요.

소재 수집은 비동기식입니다. status가 ACTIVE가 될 때까지 머티리얼 에셋 가져오기을 폴링하세요. 성공적인 HTTP 응답은 요청이 수락되었음을 의미할 뿐이므로, 항상 비즈니스 상태를 읽어야 합니다. 상태가 FAILED인 경우 error_message를 검사하고, 원본 소재를 수정한 후 새 에셋을 생성하세요.

소재 생성 요청에서 asset_url은 가져오기 원본만 의미합니다. TokenLab은 소재 에셋 id를 반환합니다. 생성 시 원본 URL 대신 이 id를 사용하십시오.

TokenLab은 소재 또는 해당 소재 그룹을 삭제할 때까지 조직 소재 라이브러리에 소재를 보관합니다. 업스트림 사본이 정리되면 자동으로 다시 생성됩니다. 위의 보관 기간 섹션을 참고하세요.

실존 인물 소재 그룹의 경우, 하나의 그룹은 한 명의 실존 인물과 매핑됩니다. 업로드는 인증된 얼굴과 대조하여 확인됩니다. 여러 얼굴이 포함되어 있거나 인증된 인물과 일치하지 않는 얼굴이 포함된 에셋은 실패할 수 있습니다. 최상의 결과를 얻으려면 전신 정면 참조 이미지와 얼굴이 명확하게 보이는 정면 클로즈업 이미지를 모두 업로드하세요.

비디오 생성에서 소재 사용Copy Anchor Link

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

REST 또는 Volcengine ActionCopy Anchor Link

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

API 예시Copy Anchor Link

가상 아바타 그룹을 생성하고, 이미지를 업로드하고, 활성화될 때까지 폴링한 다음, 비디오 요청에서 소재 에셋 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 흐름Copy Anchor Link

인증 결과가 반환한 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를 비디오 생성에 사용합니다.