본인 인증과 인물 소재
Seedance 인증, 소재 관리 및 생성에 공통으로 사용하는 APIMaster 안내.
본인 인증과 인물 소재
일반 이미지, 동영상, 오디오는 통합 소재 라이브러리를 사용합니다. 그룹 생성 시 모델과 이름만 보내고 channel_id와 purpose는 생략합니다. 서버가 대상 모델의 심사와 소재 사본을 관리합니다.
중요: 유명인과 일반인은 서로 다른 API를 사용합니다
본인 생체 인증을 시작하는 실존 인물 인증 API는 유명인에게만 필요합니다:
POST /v1/seedance2/private-avatar/verifications.일반인은
POST /v1/seedance2/private-avatar/assets를 통해 소재를 바로 심사에 제출하세요. 실존 인물 인증 API를 사용하거나 생체 인증 세션을 생성하지 마세요. 소재 상태가Active가 되면 참조할 수 있습니다.
네 모델은 동일한 APIMaster API를 사용합니다. 공급자 API, ID와 상태는 백엔드가 매핑합니다. 공식 본인 인증, 채널 인물 소재 심사, 일반 또는 가상 소재 심사는 서로 다른 절차입니다. 명시적으로 사용 허가를 받은 사진만 제출하세요.
1. 기능과 적용 범위
별도의 공식 H5 본인 인증을 사용할 때는 기능을 조회하고 official_h5 방식이 지원되는 channel_id를 선택하세요. 통합 라이브러리에 일반 소재를 제출할 때는 채널 선택이 필요하지 않습니다.
| model | duration | Image | Video | Audio |
|---|---|---|---|---|
| seedance-2.0 | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.0-fast | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.0-mini | 4–15 s | ≤9 | ≤3 / ≤15 s | ≤3 / ≤15 s |
| seedance-2.5 | 4–30 s / -1 | ≤30 | ≤10 / ≤30 s | ≤10 / ≤30 s |
통합 소재: 생성, 저장 및 재사용
일반 이미지, 동영상, 오디오는 통합 소재 라이브러리를 사용합니다. 그룹 생성 시 모델과 이름만 보내고 channel_id와 purpose는 생략합니다. 서버가 대상 모델의 심사와 소재 사본을 관리합니다.
export APIMASTER_KEY='<your APIMaster key>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/groups' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-d '{"model":"seedance-2.5","name":"My materials"}'
asset_type: Image / Video / Audio.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: unified-audio-001' \
-d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Audio","assets":[{"url":"https://your-storage.example/audio.mp3","name":"Reference audio"}]}'
반환된 group_id (data.id), asset_id, asset_url(asset:// 참조)을 저장하세요. 소재 심사를 요청한 뒤 작업, available_models, model_readiness를 조회하고 대상 모델이 준비되면 생성합니다. 동일한 소재 ID를 나중에 재사용할 수 있지만 삭제, 만료 또는 사본 추가 시 소재와 원본 접근 가능 여부를 확인해야 합니다. 공식 H5 본인 인증은 별도 절차이며 일반 소재 심사의 필수 단계가 아닙니다.
3. 휴대폰 본인 인증
이 절은 유명인에게만 해당합니다. 일반인은 본인 생체 인증을 건너뛰고 소재 제출 및 심사 절차로 바로 진행하세요.
official_h5에서는 세션 생성 후 본인의 휴대폰에서 h5_link를 엽니다. APIMaster가 HTTPS 콜백을 호스팅하므로 고객 콜백 서버는 필요 없습니다. callback_url은 보내지 마세요. 장기 키와 BytedToken은 서버에만 보관합니다. 브라우저 결과만으로 성공 처리하지 않고 서버가 공급자에게 확인합니다. 중복 콜백은 자원을 새로 만들지 않습니다.
export APIMASTER_KEY='<your APIMaster key>'
export APIMASTER_CHANNEL_ID='<available channel ID from the capability API>'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/capabilities?model=seedance-2.5' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-session-001' \
-d "{\"model\":\"seedance-2.5\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"name\":\"My portrait\"}"
4. 결과 확인
completed 이후 공개 group_id를 사용합니다. 아래 상태와 만료 시간은 인물 소재 사용 허가 기간과 다릅니다. 일시적인 네트워크 오류는 상태를 유지하며 새 세션을 자동 생성하지 않습니다. 콘솔은 /console/seedance-materials입니다. 세션, 그룹, 소재, 영상 작업은 서로 다른 ID를 사용합니다.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications/verification_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
| API | fields / values |
|---|---|
| capabilities | model, channel_id, method, configured, reason, hosted_callback, real_person_verified |
| verification | session_id (id), method, status, h5_link (verification_url), created_at, expires_at, group_id |
| verification.status | creating, pending, completed, failed, expired, failed_unconfirmed, submission_unknown |
| Idempotency-Key | 8–128; same request → original receipt; changed request → 409 |
| verification rate | ≤3 / user / minute; upstream limits also apply |
| H5 / BytedToken | single-use H5; query credential ≤30 min; expires_at ≠ portrait authorization expiry |
5. 소재 업로드와 심사
일반인은 이 절의 소재 제출 API만 사용하면 됩니다. 먼저 실존 인물 인증 API를 호출할 필요가 없습니다.
POST /uploads는 원본을 보관하고 POST /assets는 소재 심사를 요청합니다. 일반 그룹은 unified_virtual입니다. 대상 모델이 준비된 후에만 생성하세요. 공식 real_person 그룹의 새 사진은 동일인 심사가 계속 필요합니다. 일부만 성공해도 승인된 소재는 유지됩니다. 제출 결과가 불명확하면 원래 작업과 소재 ID를 보관하고 상태를 조회하며 자동으로 다시 업로드하지 마세요.
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/uploads' \
-H "Authorization: Bearer $APIMASTER_KEY" -F 'file=@authorized-owner.png'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-asset-001' \
-d '{"model":"seedance-2.5","group_id":"group_PUBLIC_ID","asset_type":"Image","assets":[{"url":"<signed upload URL>","name":"Owner"}]}'
curl --fail-with-body 'https://apimaster.ai/v1/tasks/asset_task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets?group_id=group_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/assets/asset_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
| API | fields / values |
|---|---|
| uploads | JPEG / PNG ≤10 MB; upload_id, url, url_expires_at, delete_after |
| groups | public id; group_type=unified_virtual / real_person |
| assets | public asset_id; status=Pending / Processing / Active / Failed / SubmissionUnknown |
| review task | asset_task_*; GET /v1/tasks/{id} |
6. 생성과 다운로드
생성 전 /v1/videos/quote로 견적을 확인하세요. 최고 요금 보장은 아닙니다. 서버는 소재와 호환되는 채널, 계정, 프로젝트를 유지하고 비호환 조합을 거절합니다. 모델 변경 시 해당 모델의 입력 제한을 확인하며 새 사진은 새 심사가 필요합니다. 성공 후 요금 내역을 조회하고 영상을 다운로드하세요.
curl --fail-with-body 'https://apimaster.ai/v1/videos' \
-H "Authorization: Bearer $APIMASTER_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: portrait-video-001' \
-d '{"model":"seedance-2.5","prompt":"The person smiles naturally","image_urls":["asset://asset_PUBLIC_ID"],"resolution":"480p","duration":4,"generate_audio":false}'
curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/video-requests/video_request_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/billing' -H "Authorization: Bearer $APIMASTER_KEY"
curl --fail-with-body 'https://apimaster.ai/v1/videos/task_PUBLIC_ID/content' -H "Authorization: Bearer $APIMASTER_KEY" -o owner.mp4
| API | fields / values |
|---|---|
| generation | Idempotency-Key required; no automatic POST retry |
| receipt | video_request_*; X-Seedance-Request-Id; replay → 202 + original receipt |
| video task | task_*; separate from receipt, verification and asset IDs |
7. 개인정보와 삭제
서명 링크는 민감 정보이며 유효 기간 동안 소지자가 다운로드할 수 있습니다. H5 링크, 서명 URL, 콜백 자격 증명을 로그에 남기지 마세요. 원본 삭제는 공급자 소재를 삭제하지 않습니다. 소재 삭제는 APIMaster 매핑을 제거하고 지원되는 경우에만 공급자 삭제도 수행합니다. 미지원 원격 삭제는 보장하지 않습니다. 그룹보다 소재를 먼저 삭제하세요. 생성된 영상은 자동 삭제되지 않습니다. 생체 인식 템플릿을 저장하지 않으며 심사 통과가 사용 허가를 대체하지 않습니다.
| API / storage | values |
|---|---|
| signed original URL | 1 h |
| hosted original | access ≤24 h; deletion ≤25 h |
| DELETE /uploads/{upload_id} | hosted original |
| DELETE /assets/{asset_id} | APIMaster mapping; upstream deletion if supported |
| DELETE /groups/{group_id} | empty group |
8. 요금과 오류
2026-10-07 확인: 공식 문서는 본인 인증을 한시적 무료라고 설명합니다. 세션, 심사, 업로드, 보관, 관리의 실제 요금은 문맥에 따라 다르며 모두 확인된 것은 아닙니다. 권한 패키지는 자동 구매하지 않습니다. 생성은 기존 견적, 사전 차감, 정산, 환불을 사용하며 실제 내역을 확인하세요. 오류는 권한, 기능 미지원, 인증·심사 대기 또는 실패, 소재 비호환, 공급자 결과 불확실을 구분합니다. 다른 사용자의 자원은 조회하거나 사용할 수 없습니다.
| HTTP | context |
|---|---|
| 400 | input / callback |
| 403 | permissions |
| 404 | resource |
| 409 | pending / failed review / incompatible context |
| 429 | rate limit |
| 502 / 503 | uncertain upstream result / unavailable |
가상 소재와 자동 복구
channel_id 없이 가상 그룹을 만들면 호환 모델에 동일한 asset:// ID를 참조할 수 있습니다. available_models, model_readiness, all_models_ready는 준비 상태입니다. 각 서비스의 승인은 독립적입니다. 심사 작업을 조회해 갱신하며 누락 사본 준비에는 접근 가능한 원본이 필요합니다. 명시적 채널, 기존 소재 그룹, 공식 H5 소재의 바인딩 제한은 유지됩니다.
생성에는 Idempotency-Key가 필요합니다. 접수 전 전환은 작업 ID 없는 명시적 속도 제한 거절에만 가능합니다. 접수된 작업이 명확한 계정 비활성화, 자격 증명 무효 또는 서비스 장애로 종료되면 호환 서비스가 있을 때 최대 한 번 자동 복구할 수 있습니다. 공개 작업 ID와 확정 사용자 요율을 유지하며 생성 비용을 다시 사전 차감하지 않습니다. 원래 작업과 청구 내역을 조회하세요.
대상 서비스에 호환되는 승인 사본이 있거나 독립 소재 심사를 완료해야 합니다. 다른 서비스의 승인이나 공식 H5 인증을 계정 간 복사하지 않습니다. 매개변수, 심사, 저작권 오류, 시간 초과, 연결 끊김, 접수 불명은 제외됩니다. 수동 재제출 전 접수 내역을 확인하고 new_submission_safe=true일 때만 새 키를 사용하세요.
