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

팀에서 동일한 페이스 스왑 URL을 세 개의 서로 다른 API 호출에 붙여넣어 본 적이 있다면, 왜 Seedance 자료 라이브러리가 존재하는지 이미 알고 계실 것입니다. 재사용 가능한 비디오 레퍼런스는 스프레드시트에서 복사한 일회성 URL보다 라이프사이클 상태를 가진 자산으로 관리할 때 훨씬 더 효과적입니다. TokenLab은 해당 자산을 조직 단위로 범위 지정(scope)하므로, 호출 전반에 걸쳐 레퍼런스를 저장, 검증 및 재사용할 수 있습니다. 저희는 워크플로우 형태를 테스트했습니다. 그룹은 실제 인물 자료를 구성하고, 자산은 실제 레퍼런스를 보유하며, 생성 호출은 상태가 ACTIVE에 도달한 후에만 ID를 사용합니다. 예를 들어, 이미지 링크 스프레드시트를 유지 관리하며 동일한 레퍼런스 비디오를 다섯 번씩 다시 업로드하던 팀은 이제 이 습관을 하나의 자료 자산 ID로 대체할 수 있습니다.

핵심 요약

• 자료 자산(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는 이 자료 시스템이 지원하는 현재 공개 모델 제품군입니다. 특정 티어에 대한 의존성을 구축하기 전에 문서에서 모델별 정확한 기능 세부 정보를 확인하십시오.

Seedance 자료 라이브러리: 자산 및 그룹

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

이것이 중요한 이유는 세 가지 실용적인 이유 때문입니다. 첫째, 반복적인 업로드는 대역폭을 낭비하고 모든 요청에 지연 시간을 추가하며, 특히 대용량 레퍼런스 비디오의 경우 더욱 그렇습니다. 둘째, 원시 URL은 만료되거나, 변경되거나, 원래 호스팅하던 스토리지 시스템에 의해 취소될 수 있습니다. TokenLab이 관리하는 자료 자산은 이러한 취약점이 없습니다. 셋째, 캐릭터 일관성이나 브랜드 일관성을 유지하는 비디오 파이프라인을 구축하는 팀에게 가장 중요한 점은, 자료를 사용하면 매번 생성 로직을 건드리지 않고도 버전 관리, 감사 및 교체가 가능한 안정적인 식별자를 얻을 수 있다는 것입니다.

자료 자산 vs. 자료 그룹

이 시스템의 두 가지 핵심 객체는 자료 자산과 자료 자산 그룹입니다. 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 흐름 — 검증 대상자가 호스팅된 웹 흐름을 통해 생체 검증을 완료합니다. H5는 모바일 웹 검증 인터페이스를 의미합니다.
3. 콜백 — 검증 세션이 종료되면 TokenLab이 귀하의 시스템에 알립니다.
4. 결과 바인딩 — 검증된 신원이 자료 그룹에 바인딩됩니다.
5. 그룹 범위 업로드 — 바인딩이 성공한 후에만 해당 특정 그룹에 자료 자산을 업로드할 수 있습니다.

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

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

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

모든 생성 모델이나 모든 요청 유형이 두 라이브러리 유형을 동일하게 지원한다고 가정하지 마십시오. 아키텍처를 확정하기 전에 Seedance 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 상태가 될 때까지 기다린 후 해당 ID를 사용하여 생성을 진행하십시오.

저희 파이프라인에서는 이 상태를 속도 제한 백오프(rate-limit backoff)처럼 처리합니다. 즉, 예상 가능하고 일시적이며 사용자에게 오류로 보고하는 대신 코드 내에서 처리합니다. 단일 try/catch가 아닌 작은 재시도 루프를 권장합니다.

생성에서 Seedance 자료 라이브러리 사용하기

자료 자산이(수동 업로드든 자동 준비든) 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. 지연 시간 및 품질 요구 사항에 따라 현재 Seedance 모델을 대상으로 create-video 호출에서 id를 material_asset_id로 사용하거나 material_asset_ids 내에 포함합니다.
7. 레퍼런스를 다시 업로드하는 대신 향후 생성 호출 전반에 걸쳐 동일한 자산 ID를 재사용합니다.

이는 작업 관리도 중요한 부분입니다. 재사용된 자료 자산을 기반으로 구축된 생성 호출은 중간에 중단해야 할 수도 있습니다. 이는 비용 관리, 변경된 크리에이티브 브리프 또는 잘못된 프롬프트로 인해 발생할 수 있습니다. 취소가 진행 중인 비디오 작업과 어떻게 상호 작용하는지에 대한 내용은 Seedance task cancellation에 관한 저희의 보충 글을 참조하십시오.

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

실용적인 다음 단계

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

Seedance 자산 대시보드는 이미 생성한 자산의 상태, 라이브러리 유형 및 그룹 관계를 보여줍니다.

AI 비디오 API 가격 2026 개요의 현재 요금은 비용이 사용량에 따라 어떻게 확장되는지 이해하는 데 도움이 됩니다. 또한 TokenLab 대시보드 사용량 내보내기의 지침을 사용하여 자체 사용 데이터를 추적하고 내보낼 수 있습니다.

FAQ

자료 자산과 자료 그룹은 어떻게 다릅니까?

자료 자산은 단일 재사용 레퍼런스 객체(아바타 이미지 1개, 생체 검증된 얼굴 1개, 레퍼런스 비디오 클립 1개 등)입니다. ACTIVE 상태가 되면 id가 material_asset_id가 됩니다. 자료 그룹은 group_id로 식별되는 컨테이너입니다. 그룹은 관련 자산을 구성하며 liveness_face 워크플로우에 필수적입니다. 요약하자면: group_id는 구성을 담당하고, material_asset_id는 생성을 담당합니다.

생성 호출이 409 seedance_material_preparing을 반환하는 이유는 무엇입니까?

image_url 또는 start_image와 같은 호환되는 이미지 필드에 의해 트리거되는 자동 자료 준비는 60초 이상 걸릴 수 있습니다. 이 경우 API는 auto_material_asset_ids와 함께 409 seedance_material_preparing을 반환합니다. 해당 ID를 폴링하고 ACTIVE가 될 때까지 기다린 후 생성을 재시도하십시오. 이는 실패가 아니라 일시적인 진행 상태를 나타냅니다.

실제 인물 레퍼런스는 항상 검증이 필요합니까?

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

하나의 자료 자산을 여러 Seedance 비디오 작업에서 재사용할 수 있습니까?

네, 자산이 ACTIVE 상태에 도달하면 가능합니다. create-video 호출에서 해당 id를 material_asset_id로 사용하거나 material_asset_ids 내에 포함하십시오. 레퍼런스를 다시 업로드하는 대신 향후 생성 호출 전반에 걸쳐 동일한 자산 ID를 재사용하십시오. 진행 중인 작업을 중단해야 하는 경우 Seedance task cancellation을 참조하십시오.

출처 및 최신성

• Seedance 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 자산 대시보드 — /dashboard/seedance-assets — 2026-07-09 확인됨

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

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