> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 소재 및 실존 인물 인증

> 재사용 가능한 Seedance 소재를 만들고 실존 인물을 인증한 뒤 활성 소재를 비디오 생성에 사용합니다.

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

## 소재 워크플로 선택

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

## 소재 개념

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 참조로 사용하기 전에 동의 및 얼굴 확인이 필요한 경우 실존 인물 소재 확인을 사용하세요.

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

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

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

## 소재 그룹 생성

`aigc_avatar` 그룹의 경우 [머티리얼 에셋 그룹 생성](/ko/api-reference/video/create-material-asset-group)을 사용하세요. 새로운 실존 인물 그룹은 인증된 인물과 소재 그룹이 연결된 상태를 유지하도록 확인 흐름을 통해 생성됩니다.

그룹이 생성된 후 관리하려면 [머티리얼 에셋 그룹 목록 조회](/ko/api-reference/video/list-material-asset-groups), [머티리얼 에셋 그룹 가져오기](/ko/api-reference/video/get-material-asset-group), [머티리얼 에셋 그룹 업데이트](/ko/api-reference/video/update-material-asset-group) 및 [머티리얼 에셋 그룹 삭제](/ko/api-reference/video/delete-material-asset-group)을 사용하세요.

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

## 소재 업로드

[머티리얼 에셋 생성](/ko/api-reference/video/create-material-asset)을 사용하여 공개적으로 접근 가능한 소스 URL을 한 번에 하나씩 가져옵니다.

`aigc_avatar`의 경우 `group_id`는 선택 사항이며, TokenLab은 조직 기본 가상 아바타 그룹을 사용하거나 생성합니다. `liveness_face`의 경우 `group_id`가 필수이며, [시각 인증 결과 조회](/ko/api-reference/video/get-visual-validation-result)에서 반환된 그룹이어야 합니다.

| 유형  | 지원되는 입력                                                                                                                                     |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 이미지 | `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`가 될 때까지 [머티리얼 에셋 가져오기](/ko/api-reference/video/get-material-asset)을 폴링하세요. 성공적인 HTTP 응답은 요청이 수락되었음을 의미할 뿐이므로, 항상 비즈니스 상태를 읽어야 합니다. 상태가 `FAILED`인 경우 `error_message`를 검사하고, 원본 소재를 수정한 후 새 에셋을 생성하세요.

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

TokenLab은 소재 또는 해당 소재 그룹을 삭제할 때까지 조직 소재 라이브러리에 소재를 보관합니다.

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

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

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

## REST 또는 Volcengine Action

TokenLab 네이티브 통합은 snake\_case `/v1/videos/assets*` REST API를 계속 사용할 수 있습니다. 기존 Volcengine 클라이언트는 PascalCase 본문을 유지하고 [Volcengine 호환 소재 Action](/ko/api-reference/video/volc-compatible-material-actions)을 사용할 수 있습니다. 두 방식은 같은 조직 및 프로젝트 범위 소재 데이터를 조작합니다.

## API 예시

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

```bash theme={null}
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"
```

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

```bash theme={null}
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`에 전달합니다.

```bash theme={null}
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를 비디오 생성에 사용합니다.