미디어 가이드
Seedance 자료 및 실존 인물 인증
Seedance에서 이미지, 비디오, 오디오 또는 인증된 인물을 재사용하는 방법
Seedance 자료를 사용하면 이미지, 비디오 또는 오디오 파일을 생성할 때마다 가져올 필요 없이 재사용할 수 있습니다. 실존 인물에 대한 참조는 동의 및 시각적 인증이 필요하지만, 가상 인물, 제품 및 스타일은 그렇지 않습니다.
자료 유형 선택
| 재사용하려는 대상 | 수행 작업 |
|---|---|
| 한 번 사용하는 이미지 | 지원되는 이미지 필드에 해당 URL을 전송합니다. 이 방식은 재사용 가능한 자료 ID를 생성하지 않습니다. |
| 가상 인물, 제품 또는 스타일 재사용 | aigc_avatar 그룹을 생성하고, 에셋을 생성한 뒤 ACTIVE 상태가 될 때까지 기다렸다가 해당 에셋 ID를 사용합니다. |
| 실존 인물 재사용 | 시각적 검증을 완료하고 GroupId를 받은 뒤, 해당 그룹에 에셋을 생성하고 ACTIVE 상태가 될 때까지 기다렸다가 해당 에셋 ID를 사용합니다. |
| 기존 Volcengine 자료 클라이언트 마이그레이션 | Action 요청 형식을 유지하고 Volc 호환 자료 참조를 사용합니다. |
그룹 및 자료
| 항목 | REST 필드 | Action 필드 | 의미 |
|---|---|---|---|
| 자료 그룹 | group_id | GroupId | 관련 자료를 함께 보관합니다. |
| 자료 | id | Id | 가져온 이미지, 비디오 또는 오디오 파일 하나입니다. 활성화된 후 이 ID를 사용합니다. |
| 가상 아바타 그룹 | library_type: "aigc_avatar" | GroupType: "AIGC" | 실존 인물 인증이 필요하지 않습니다. |
| 실존 인물 그룹 | library_type: "liveness_face" | GroupType: "LivenessFace" | 성공적인 시각적 검증 흐름을 통해서만 생성됩니다. |
| 프로젝트 이름 | project_name | ProjectName | 서로 다른 프로젝트의 자료를 분리하여 보관합니다. 기본값은 default입니다. |
그룹 ID와 에셋 ID를 구분하여 관리하십시오. 그룹은 업로드를 구성하며, 에셋 ID는 비디오 생성 시 사용하는 참조값입니다. 공개 ID는 group-20260720123456-vrt01 및 asset-20260720123457-def45와 같은 형태입니다.
자료 보관
TokenLab은 에셋이나 해당 그룹을 삭제할 때까지 모든 자료 에셋을 보관합니다. 비활성 상태라고 해서 자동으로 정리되지 않습니다.
- 에셋을 사용할 때 다시 준비해야 하는 경우, 첫 번째 생성에 시간이 조금 더 걸릴 수 있습니다. 아직 준비되지 않은 경우 요청은
409 seedance_material_preparing을 반환하므로 잠시 후 다시 시도하십시오. - 에셋이나 그룹을 삭제하면 영구적으로 복구할 수 없습니다.
이미지 URL 및 재사용 가능한 자료
선택한 모델에서 허용하는 이미지 필드에 공개 HTTP(S) URL 또는 지원되는 데이터 URL을 전송하십시오. 이러한 입력은 일반적인 미디어 경로를 따르며 재사용 가능한 자료 ID를 자동으로 생성하지 않습니다.
재사용 가능한 자료의 경우, 자료 API를 통해 에셋을 생성하고 ACTIVE 상태가 될 때까지 기다린 다음, 지원되는 미디어 필드에서 material_asset_id, material_asset_ids 또는 asset://<id>를 사용하십시오. 의도한 첫 번째 프레임, 마지막 프레임 또는 참조 이미지 역할을 유지하십시오.
명시적 자료가 준비 중인 경우, POST /v1/videos/generations는 inactive_asset_ids와 함께 409 seedance_material_preparing을 반환합니다. 해당 에셋들이 ACTIVE 상태가 될 때까지 폴링한 후 동일한 자료 ID로 다시 시도하십시오. 에셋이 FAILED 상태인 경우 error_message를 확인하고 수정하거나 재가져오기한 후 다시 시도하십시오. 실패한 에셋을 사용하는 생성 요청은 failed_asset_ids와 함께 422 seedance_material_failed를 반환합니다.
가상 아바타 자료
자료 에셋 그룹 생성을 사용하여 aigc_avatar 그룹을 만드십시오. REST 에셋 생성 시 project_name이 default인 경우에만 group_id가 선택 사항이며, 이 경우 TokenLab은 조직의 기본 가상 아바타 그룹을 사용하거나 생성합니다. project_name이 기본값이 아니거나 실존 인물 에셋인 경우에는 group_id가 필수입니다.
그룹이 생성된 후에는 다음을 사용하여 관리할 수 있습니다.
그룹을 삭제하면 해당 그룹에 포함된 TokenLab 자료도 함께 삭제되며 복구할 수 없습니다.
실존 인물 인증
제품에서 실존 인물을 Seedance 참조로 재사용하기 전에 동의를 수집하고 얼굴을 인증해야 하는 경우 이 흐름을 사용하십시오.
CallbackURL과 함께 시각적 검증 세션 생성을 호출합니다.Result.BytedToken을 저장하고 인증받을 인물을 위해Result.H5Link를 엽니다.- H5 흐름이 콜백으로 리디렉션된 후, 동일한
BytedToken및ProjectName으로 시각적 검증 결과 조회를 폴링합니다. - 반환된
Result.GroupId를 저장합니다. TokenLab은 이 단계에서LivenessFace그룹을 생성하고 바인딩합니다. - 해당 그룹 ID로 에셋을 생성한 다음, 에셋이
ACTIVE상태가 될 때까지 폴링합니다.
BytedToken은 30분 동안 유효합니다. 클라이언트는 CreateAssetGroup으로 LivenessFace 그룹을 생성할 수 없습니다. 이는 인증되지 않은 그룹이 인증된 것처럼 표시되는 것을 방지하기 위함입니다.
생성 직후 반환된 H5Link를 여십시오. 토큰 유효 기간이 해당 시간 내에 언제든지 인증 페이지를 처음 열 수 있다는 것을 의미하지는 않습니다.
실존 인물 그룹의 경우, 업로드된 파일은 인증된 얼굴과 대조됩니다. 에셋에 여러 얼굴이 포함되어 있거나 얼굴이 일치하지 않으면 에셋이 실패할 수 있습니다. 최상의 결과를 얻으려면 전신 정면 참조 이미지와 얼굴이 명확하게 보이는 정면 근접 사진을 업로드하십시오.
에셋 생성 및 준비
자료 에셋 생성을 사용하여 공개적으로 접근 가능한 URL을 한 번에 하나씩 가져오십시오.
| 유형 | 지원되는 입력 |
|---|---|
| 이미지 | jpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; 가로 및 세로 [300, 6000] px; 종횡비 [0.4, 2.5] |
| 비디오 | mp4, mov; ≤ 200 MiB |
| 오디오 | aac, wav, mp3; ≤ 15 MiB |
위 내용은 파일 가져오기 제한입니다. 가져오기 요청이 성공했다고 해서 미디어 또는 실존 인물 검증이 통과되는 것은 아닙니다. ACTIVE 상태가 될 때까지 기다리십시오. 에셋이 FAILED 상태가 되면 error_message를 사용하여 소스를 수정한 후 다시 가져오십시오.
자료 수집은 비동기식으로 진행됩니다. status가 ACTIVE가 될 때까지 자료 에셋 조회를 폴링하십시오. HTTP 성공은 가져오기가 수락되었음을 의미할 뿐, 에셋이 준비되었음을 의미하지는 않습니다. 에셋이 FAILED 상태가 되면 error_message를 확인하고 소스를 수정한 뒤 새 에셋을 생성하십시오.
소스 URL은 가져오기 용도로만 사용됩니다. TokenLab은 자체 에셋 ID를 반환하며, 에셋이나 그룹을 삭제할 때까지 조직의 자료 라이브러리에 에셋을 보관합니다.
비디오 생성 시 에셋 사용
에셋이 ACTIVE 상태가 된 후, 비디오 생성 호출 시 다음 형식 중 하나를 선택하십시오.
- 단일 일반 자료 참조의 경우
material_asset_id - 다중 일반 참조의 경우
material_asset_ids - 미디어 역할을 명시해야 할 때
image_url,start_image,end_image또는reference_images내의asset://<asset-id>
자료 참조는 선택한 모델의 Seedance 참조 제한에 포함됩니다. API가 Seedance material asset not found or not accessible을 반환하는 경우, 해당 값이 그룹 ID가 아닌 에셋 ID인지, 동일한 조직 및 프로젝트에 속하는지, 삭제되지 않았는지, 그리고 ACTIVE 상태인지 확인하십시오.
REST 또는 Volcengine Action
TokenLab 네이티브 통합은 계속해서 snake_case 형식의 /v1/videos/assets* REST 엔드포인트를 사용할 수 있습니다. 기존 Volcengine 클라이언트는 자료 작업 (Volc 호환)을 통해 PascalCase 본문을 유지할 수 있습니다. 두 인터페이스 모두 동일한 조직 및 프로젝트 범위의 자료 데이터를 처리합니다.
REST 예시: 가상 아바타 에셋
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","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
-H "Authorization: Bearer $TOKENLAB_API_KEY"Action 예시: 인증된 실존 인물 에셋
먼저 시각적 검증을 생성하고 완료하십시오.
curl 'https://api.tokenlab.sh/?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/?Action=GetVisualValidateResult&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'그런 다음 반환된 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"
}'상태가 Active가 될 때까지 GetAsset으로 폴링한 다음, 반환된 에셋 ID를 비디오 생성에 전달하십시오. 10가지 모든 Action 작업, 필터, 페이지네이션, 응답 형태 및 오류에 대한 자세한 내용은 자료 작업 (Volc 호환)을 참조하십시오.