본인 인증과 인물 소재
Seedance 인증, 소재 관리 및 생성에 공통으로 사용하는 APIMaster 안내.
본인 인증과 인물 소재
네 모델은 동일한 APIMaster API를 사용합니다. 공급자 API, ID와 상태는 백엔드가 매핑합니다. 공식 본인 인증, 채널 인물 소재 심사, 일반 또는 가상 소재 심사는 서로 다른 절차입니다. 명시적으로 사용 허가를 받은 사진만 제출하세요.
1. 기능과 적용 범위
APIMaster 키로 기능을 조회하고 반환된 channel_id로 문맥을 고정합니다. 지원 여부는 권한, 프로젝트 및 모델 라우팅에 따라 달라집니다. 지원하지 않으면 거절하며 채널이나 모델을 자동 변경하지 않습니다. SD1.0, SD1.5 및 사용자 별칭은 프로토콜을 별도로 확인해야 합니다.
| 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 |
2. 처리 방식 선택
official_h5는 세션을 만들고 본인이 휴대폰에서 인증해야 합니다. channel_material_review는 purpose=channel_portrait 그룹을 만든 뒤 소재를 제출하고 조회합니다. owner_verified=false는 공식 본인 인증을 의미하지 않습니다. 지원하는 경우 일반 소재는 purpose=ordinary를 사용합니다. virtual_or_ordinary는 공식 본인 인증을 제공하지 않으며 unverified는 기능 미확인입니다. purpose를 생략하면 기존 가상 그룹 동작을 유지합니다.
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\",\"channel_id\":${APIMASTER_CHANNEL_ID},\"purpose\":\"channel_portrait\",\"name\":\"Authorized portrait materials\"}"
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. 소재 업로드와 심사
POST /uploads는 원본 파일만 보관합니다. POST /assets가 공통 소재 등록·심사 API이며 기존 POST /v1/seedance2/private-avatar는 같은 처리의 호환 경로입니다. Active만 생성에 사용할 수 있고 Processing, Pending, Failed는 사용할 수 없습니다. 공식 real_person 그룹의 새 사진은 동일인 심사를 거칩니다. channel_portrait는 소재 심사입니다. 부분 성공은 승인된 소재를 보존합니다. 시간 초과 후 기존 소재를 조회하고 POST를 자동 재전송하거나 asset_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=virtual / ordinary / channel_portrait / real_person |
| assets | public asset_id; status=Pending / Processing / Active / Failed |
| channel_material_review | verification_method, owner_verified=false, material_purpose, review.scope_model |
| 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; hourly cleanup ≤25 h; private files 0600 |
| 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 |