TokenLab Seedance Materials: 프로덕션 워크플로우를 위한 재사용 가능한 비디오 레퍼런스

재사용 가능한 비디오 레퍼런스는 모든 생성 요청에 복사되는 일회성 URL이 아니라, 라이프사이클 상태를 가진 자산으로 관리할 때 훨씬 더 편리합니다. 이미지 링크 스프레드시트를 관리하거나, 동일한 레퍼런스 비디오를 다섯 번씩 다시 업로드하거나, 세 가지 다른 API 호출에 페이스 스왑 URL을 일일이 다시 입력해 본 적이 있다면, Seedance 자료가 해결하고자 하는 문제를 이미 이해하고 계실 것입니다.

TokenLab의 Seedance 자료 라이브러리는 비디오 팀이 생성 호출 전반에 걸쳐 레퍼런스를 저장, 검증 및 재사용할 수 있는 조직 단위의 방법을 제공합니다. 이 기사에서는 자료 자산(material asset)이 실제로 무엇인지, 자료 그룹(material group)이 개별 자산과 어떻게 관련되는지, 자동 준비 기능은 어떻게 작동하는지, 그리고 실제 인물 검증이 워크플로우의 어디에 위치하는지 설명합니다.

핵심 요약

• 자료 자산(material asset)은 생성 준비가 완료된 레퍼런스 객체이며, 자료 그룹(material group)은 특히 실제 인물 워크플로우를 위해 관련 자산을 구성하는 컨테이너입니다.
• 자료 자산의 상태가 ACTIVE에 도달한 후에만 해당 자산의 id를 material_asset_id(또는 material_asset_ids 내부)로 사용하십시오.
• 두 가지 라이브러리 유형이 존재합니다: 가상 아바타 및 기타 비실제 인물 재사용 레퍼런스를 위한 aigc_avatar와 검증이 필요한 실제 인물 자료 그룹을 위한 liveness_face입니다.
• TokenLab은 별도의 업로드 단계 없이 호환되는 이미지 입력(image, image_url, image_urls, reference_images, start_image, end_image)을 자료 자산으로 자동 준비할 수 있습니다.
• 준비 과정이 60초를 초과하면 API는 409 seedance_material_preparing과 함께 폴링 및 재시도할 수 있는 auto_material_asset_ids를 반환합니다.
• Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini는 이 자료 시스템이 지원하는 현재 공개 모델입니다. 특정 티어에 의존성을 구축하기 전에 문서에서 모델별 기능 세부 정보를 확인하십시오.

Seedance 자료란 무엇인가

Seedance 자료는 TokenLab이 요청 단위의 URL이 아닌 조직 단위의 자산으로 저장하는 재사용 가능한 레퍼런스(이미지, 비디오 또는 오디오)입니다. 모든 create-video 호출에 원본 파일 링크를 전달하는 대신, 레퍼런스를 한 번 업로드하거나 가져온 다음 생성 준비가 완료될 때까지 기다렸다가 필요한 만큼 후속 호출에서 ID로 참조하면 됩니다.

이것이 중요한 이유는 세 가지 실용적인 이유 때문입니다.

첫째, 반복적인 업로드는 대역폭을 낭비하고 특히 대용량 레퍼런스 비디오의 경우 모든 요청에 지연 시간을 추가합니다.

둘째, 원본 URL은 만료되거나, 변경되거나, 원래 호스팅하던 스토리지 시스템에 의해 취소될 수 있습니다. TokenLab이 관리하는 자료 자산은 이러한 불안정성이 없습니다.

셋째, 캐릭터 일관성이나 브랜드 일관성을 갖춘 비디오 파이프라인을 구축하는 팀에게 가장 중요한 점은, 자료가 매번 생성 로직을 건드리지 않고도 버전 관리, 감사 및 교체가 가능한 안정적인 식별자를 제공한다는 것입니다.

자료 자산(Material Assets) vs. 자료 그룹(Material Groups)

이 시스템의 두 가지 핵심 객체는 자료 자산과 자료 자산 그룹이며, API 레퍼런스를 자세히 읽지 않으면 혼동하기 쉽습니다.

자료 자산(material asset)은 단일 레퍼런스 객체(아바타 이미지 1개, 실사 검증된 얼굴 1개, 레퍼런스 비디오 클립 1개 등)입니다. 생성 시 API는 id를 반환합니다. 이 id는 자산이 ACTIVE 상태에 도달하면 비디오 생성 호출에 전달하게 됩니다.

자료 자산 그룹(material asset group)은 group_id로 식별되는 컨테이너입니다. 그룹은 관련 자산을 함께 구성하며, 실제 인물(liveness_face) 워크플로우의 경우 구조적으로 필수적입니다. 이 워크플로우에서는 개별 자산을 업로드하기 전에 그룹 수준에서 검증이 이루어져야 합니다.

요약하자면: group_id는 구성하고, material_asset_id는 생성합니다. API의 여러 부분에서 두 필드를 모두 보게 될 것이며, 잘못된 위치에 잘못된 필드를 사용하는 것은 팀이 이 시스템을 통합할 때 가장 흔히 저지르는 실수입니다.

필드	식별 대상	사용 위치
group_id	자료 자산 그룹(컨테이너)	그룹 생성 또는 참조(특히 실제 인물 검증 흐름)
id (자료 자산의 경우)	단일 재사용 레퍼런스	ACTIVE 상태가 되면 material_asset_id가 됨
material_asset_id	단일 자산 레퍼런스	하나의 레퍼런스 슬롯을 위해 create-video에 전달
material_asset_ids	자산 레퍼런스 배열	여러 재사용 레퍼런스가 필요할 때 create-video에 전달

전체 필드 정의 및 필수 매개변수는 create material asset 및 create material asset group API 레퍼런스에 문서화되어 있습니다. 프로덕션 코드에 연결하기 전에 해당 문서를 읽으십시오. 이 기사는 워크플로우의 형태를 다루며 모든 요청 매개변수를 다루지는 않습니다.

가상 아바타 및 실제 인물 워크플로우

Seedance 자료는 두 가지 라이브러리 유형을 지원하며, 이 구분은 단순히 외형적인 것이 아니라 두 가지 다른 안전 및 동의 태도를 반영합니다.

aigc_avatar: 가상 아바타 및 비실제 인물 레퍼런스

aigc_avatar 유형은 검증된 실제 인물과 연결되지 않은 재사용 가능한 레퍼런스(일러스트 캐릭터, 합성 아바타, 스타일화된 인물, 제품 마스코트 및 유사 자산)를 다룹니다. 이러한 자산은 검증 단계 없이 자료 자산 생성 흐름을 통해 직접 생성할 수 있습니다.

귀하의 제품이 가상의 캐릭터나 브랜드 아바타를 중심으로 비디오를 생성한다면, 거의 확실히 이 라이브러리 유형이 필요할 것입니다. 신원 확인 요구 사항이 없기 때문에 생성 경로가 더 간단합니다.

liveness_face: 실제 인물 자료 그룹

liveness_face 유형은 실제 인물의 외모를 중심으로 구축된 자료 그룹을 위한 것입니다. 이는 실제 개인을 특징으로 하는 얼굴 일관성 비디오 생성에 사용되는 레퍼런스 유형입니다. 이는 신원 및 동의와 관련이 있으므로, TokenLab은 자산을 그룹에 업로드하기 전에 검증 흐름을 요구합니다.

검증 시퀀스에는 몇 가지 구별되는 단계가 있습니다:

1. 세션 생성 — 백엔드에서 그룹에 대한 검증 세션을 요청합니다.
2. H5 흐름 — 검증 대상자가 호스팅된 웹 흐름을 통해 생체 인식(liveness check)을 완료합니다(H5는 모바일 웹 검증 인터페이스를 의미합니다).
3. 콜백 — 검증 세션이 종료되면 TokenLab이 귀하의 시스템에 알립니다.
4. 결과 바인딩 — 검증된 신원이 자료 그룹에 바인딩됩니다.
5. 그룹 단위 업로드 — 바인딩이 성공한 후에만 해당 특정 그룹에 자료 자산을 업로드할 수 있습니다.

즉, 실제 인물 자료는 본질적으로 그룹 우선입니다. aigc_avatar처럼 바로 자산을 생성할 수 없습니다. 그룹이 존재하고 검증을 통과해야만 자산 업로드가 유효합니다.

체크리스트: 올바른 라이브러리 유형 선택

• 레퍼런스가 실제 식별 가능한 사람의 얼굴이나 외모인가요? → liveness_face를 사용하고 검증 흐름을 계획하십시오.
• 레퍼런스가 합성, 일러스트 또는 비실제 인물 아바타인가요? → aigc_avatar를 사용하고 검증을 건너뛰십시오.
• 동일한 실제 인물에 대해 여러 생성물에서 일관된 신원이 필요한가요? → 그룹을 한 번 구축하고, 한 번 검증한 후 향후 자산을 위해 그룹을 재사용하십시오.
• 고객이 제공한 레퍼런스가 어떤 유형에 해당하는지 확실하지 않나요? → 확인되기 전까지는 liveness_face로 취급하십시오. 문서에서 확인하고 추측하지 마십시오.

모든 생성 모델이나 모든 요청 유형이 두 라이브러리 유형을 동일하게 지원한다고 가정하지 마십시오. 아키텍처를 확정하기 전에 Seedance 2.0 Video Models 가이드에서 현재 지원 여부를 확인하십시오.

자동 자료 준비 기능의 작동 방식

모든 레퍼런스가 수동 업로드 단계를 거칠 필요는 없습니다. TokenLab은 생성 요청의 일부로 호환되는 이미지 입력을 자료 자산으로 자동 준비할 수 있으므로, 간단한 경우 왕복 단계를 줄여줍니다.

자동 준비를 위해 인식하는 필드는 다음과 같습니다:

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

이 중 하나를 생성 호출에 직접 전달하면, TokenLab은 별도로 자료 자산 엔드포인트를 먼저 호출하도록 요구하는 대신 백그라운드에서 가져오기 및 준비를 처리합니다.

준비 시간이 60초를 초과할 경우

준비는 일반적으로 빠르지만, 더 크거나 복잡한 레퍼런스 이미지는 생성 준비가 완료된 자산으로 처리되는 데 시간이 더 걸릴 수 있습니다. 준비 시간이 60초를 초과하면 API는 다음을 응답합니다:

409 seedance_material_preparing

이와 함께 여전히 준비 중인 자산의 ID를 포함하는 auto_material_asset_ids 필드가 반환됩니다.

이는 일반적인 의미의 오류가 아니라 재시도하라는 신호입니다. 귀하의 통합 코드는 409 seedance_material_preparing을 최종 사용자에게 보고할 실패가 아닌 "잠시 후 다시 확인" 응답으로 처리해야 합니다. 반환된 자산 ID를 폴링하고 ACTIVE 상태가 될 때까지 기다린 후 생성을 진행하십시오.

실질적으로 이는 귀하의 생성 파이프라인에 단일 try/catch가 아닌 작은 재시도 루프가 필요함을 의미합니다. 자동화된 비디오 파이프라인을 구축하는 팀은 이 상태를 속도 제한 백오프(rate-limit backoff)와 동일하게 취급해야 합니다. 즉, 예상되는 일시적인 현상이며 사용자에게 오류로 보고하는 대신 코드 내에서 처리해야 합니다.

생성 시 자료를 사용하는 방법

자료 자산이 수동으로 업로드되었든 자동으로 준비되었든 ACTIVE 상태에 도달하면, 해당 id는 create video 호출에서 material_asset_id(또는 material_asset_ids의 항목)로 사용할 수 있게 됩니다.

핵심 워크플로우는 다음과 같습니다:

1. 레퍼런스가 실제 인물인지 여부를 결정합니다. 그에 따라 liveness_face(검증 포함) 또는 aigc_avatar를 선택합니다.
2. 실제 인물인 경우: 자료 그룹을 생성하고, 검증 세션 및 H5 흐름을 실행하고, 콜백을 수신하고, 결과를 바인딩합니다.
3. 자료 자산을 생성하거나 가져옵니다(직접 업로드 호출을 통하거나, 생성 요청 내의 호환되는 이미지 필드가 자동 준비를 처리하도록 함).
4. 상태를 확인합니다. ACTIVE로 보고될 때까지 자산 ID를 생성에 전달하지 마십시오.
5. 409 seedance_material_preparing이 발생하면 반환된 auto_material_asset_ids를 폴링하고 ACTIVE로 해결되면 재시도합니다.
6. create-video 호출에서 id를 material_asset_id로 사용하거나 material_asset_ids 내에 포함시키며, 지연 시간 및 품질 요구 사항에 따라 seedance-2.0, seedance-2.0-fast 또는 seedance-2.0-mini와 같은 현재 Seedance 모델을 타겟팅합니다.
7. 레퍼런스를 다시 업로드하는 대신 향후 생성 호출 전반에 걸쳐 동일한 자산 ID를 재사용합니다.

이는 작업 관리도 중요한 부분입니다. 재사용된 자료 자산을 기반으로 한 생성 호출을 실행 중간에 중단해야 하는 경우(비용 관리, 변경된 크리에이티브 브리프 또는 잘못된 프롬프트 때문), 취소가 진행 중인 비디오 작업과 어떻게 상호 작용하는지에 대한 Seedance task cancellation 관련 문서를 참조하십시오.

TokenLab의 비디오 생성 모델 전반에 걸쳐 현재 사용 가능한 기능에 대한 더 광범위한 비교는 비디오 모델 카테고리 페이지에서 현재 옵션을 나란히 나열하고 있습니다.

실질적인 다음 단계

• 프로토타이핑 중이라면 aigc_avatar 자료로 시작하십시오. 생성 경로가 더 간단하며 구축해야 할 검증 의존성이 없습니다.
• 제품에 실제 인물 일관성이 필요한 경우, 검증 흐름(세션 → H5 → 콜백 → 바인딩)을 온보딩의 일등석 부분으로 구축하십시오.
• 프로덕션에 배포하기 전에 409 seedance_material_preparing에 대한 재시도 루프를 추가하십시오. 이를 엣지 케이스가 아닌 예상되는 동작으로 취급하십시오.
• 어떤 자산이 어떤 캐릭터나 제품에 매핑되는지 다시 파생할 필요가 없도록 자체 내부 레퍼런스 기록과 함께 자료 자산 ID를 저장하십시오.
• 자료 자산 및 자료 자산 그룹 API 레퍼런스를 직접 검토하십시오. 이 기사는 워크플로우의 형태를 설명하며, 통합 코드를 작성하기 전에 정확한 요청/응답 필드를 현재 문서와 대조하여 확인해야 합니다.

이미 생성한 자산의 상태, 라이브러리 유형 및 그룹 관계를 확인하려면 Seedance 자산 대시보드에서 자료 라이브러리를 직접 탐색할 수 있습니다.

프로덕션 워크플로우를 확정하기 전에 AI 비디오 API 가격 2026 개요에서 현재 요금을 검토하여 비용이 사용량에 따라 어떻게 확장되는지 이해하는 것이 좋습니다. 또한 TokenLab 대시보드 사용량 내보내기의 지침을 사용하여 자체 사용량 데이터를 추적하고 내보낼 수 있습니다.

FAQ

Seedance 자료 자산이란 무엇인가요? 자료 자산은 자체 라이프사이클 상태를 가진 조직 단위 객체로 저장되는 재사용 가능한 비디오 생성 레퍼런스(이미지, 비디오 또는 오디오)입니다. ACTIVE 상태에 도달하면 매번 원본 URL을 다시 제공하는 대신 여러 생성 호출에서 ID로 참조할 수 있습니다.

group_id와 material_asset_id의 차이점은 무엇인가요? group_id는 주로 실제 인물(liveness_face) 자산을 구성하고 그룹 수준에서 검증을 관리하는 데 사용되는 컨테이너인 자료 자산 그룹을 식별합니다. material_asset_id는 단일 재사용 레퍼런스를 식별하며(자료 자산 생성 시 반환되는 id), 비디오 생성 호출에 전달하는 값입니다.

언제 실제 인물 검증을 사용해야 하나요? 레퍼런스 자료에 실제 식별 가능한 사람의 얼굴이나 외모가 포함된 경우 liveness_face 유형과 해당 검증 흐름을 사용하십시오. 이 흐름은 해당 그룹에 자산을 업로드하기 전에 세션 생성, H5 생체 인식 확인, 콜백 및 바인딩 단계를 거쳐야 합니다. 일러스트나 합성 아바타와 같은 비실제 인물 레퍼런스는 aigc_avatar를 사용하며 이 검증 경로가 필요하지 않습니다.

seedance_material_preparing은 무엇을 의미하나요? 이는 생성 요청에서 image_url 또는 start_image와 같은 호환되는 이미지 필드에 의해 트리거되는 자동 자료 준비가 완료되는 데 60초 이상 걸릴 때 반환되는 409 응답입니다. 응답에는 auto_material_asset_ids가 포함되어 있어 해당 ID를 폴링하고 ACTIVE가 되면 생성을 재시도할 수 있습니다. 이는 실패가 아닌 진행 중인 일시적인 상태를 나타냅니다.

출처 및 최신 정보

• Seedance 2.0 Video Models 가이드 — https://docs.tokenlab.sh/guides/seedance-2-video — 2026-07-09 확인됨
• Seedance 자료 자산 생성 (API 레퍼런스) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — 2026-07-09 확인됨
• Seedance 자료 자산 그룹 생성 (API 레퍼런스) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — 2026-07-09 확인됨
• 비디오 생성 (API 레퍼런스) — https://docs.tokenlab.sh/api-reference/video/create-video — 2026-07-09 확인됨
• TokenLab Seedance 자산 대시보드 — https://tokenlab.sh/en/dashboard/seedance-assets — 2026-07-09 확인됨

여기에 설명된 API 동작, 필드 이름 및 상태 의미 체계는 확인 날짜 기준의 공개 문서 및 대시보드 사본을 반영합니다. TokenLab의 Seedance 자료 시스템은 활발히 개발 중이므로, 프로덕션 통합 코드를 마무리하기 전에 링크된 문서에서 현재 매개변수 이름, 상태 값 및 모델별 지원 여부를 확인하십시오.

안정적이고 재사용 가능한 레퍼런스에 의존하는 비디오 파이프라인을 구축 중이라면 Seedance 2.0 Video Models 가이드로 시작하십시오. 현재 매개변수 이름을 확인하고 타겟 모델 티어가 실제로 무엇을 지원하는지 확인하는 가장 빠른 방법입니다.