Owner verification and portrait assets

Use the unified material library for ordinary images, videos and audio. Create a group with only the model and name; omit channel_id and purpose. The backend manages review and material copies for the target models.

Important: celebrities and non-celebrities use different workflows

Only celebrities need the real-person verification endpoint to start owner liveness verification: POST /v1/seedance2/private-avatar/verifications.

Non-celebrities should submit their materials directly for review through POST /v1/seedance2/private-avatar/assets. Do not use the real-person verification endpoint or create a liveness-verification session. Reference the asset once its status is Active.

Availability depends on the selected channel configuration and account entitlement. Official H5 verification must be completed by the owner on their phone; channel material review follows the channel background workflow. Ordinary material review, virtual portrait review and intermediary automatic approval do not prove official owner verification.

All four public model IDs use the same verification and asset service: seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-2.5. SD1.0, SD1.5 and custom aliases require separate exact upstream protocol verification. Real people, virtual portraits and ordinary material review are different workflows.

Availability depends on APIMaster configuration, permissions, project and model routing. Account entitlements and upstream credentials are managed by the platform. Missing capabilities or entitlements produce explicit errors without switching channels, activating entitlements or purchasing packages automatically.

Capability and scope

Call GET /v1/seedance2/private-avatar/capabilities?model=seedance-2.5 with your APIMaster Bearer key. Each eligible channel includes channel_id, method, configured, reason and real_person_verified. Configured asset credentials do not prove account entitlement.

Model	APIMaster verification and asset endpoints	Available capabilities
seedance-2.0	Shared endpoints in this guide	Determined by capability discovery
seedance-2.0-fast	Shared endpoints in this guide	Determined by capability discovery
seedance-2.0-mini	Shared endpoints in this guide	Determined by capability discovery
seedance-2.5	Shared endpoints in this guide	Determined by capability discovery

Clients use APIMaster authentication, public session/group/asset IDs and the endpoints in this guide. The backend maps upstream paths, credentials, asset IDs and review statuses; clients do not need supplier-specific requests. channel_id is an APIMaster routing identifier used to bind the material context, not an upstream account or asset ID.

An explicitly selected unsupported channel is rejected without changing channels or models. Availability is determined by the capability API and server-confirmed upstream results.

Unified materials: create, save and reuse

Use the unified material library for ordinary images, videos and audio. Create a group with only the model and name; omit channel_id and purpose. The backend manages review and material copies for the target models.

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"}]}'

Save the returned group_id (data.id), asset_id and asset_url (asset:// reference). Submit materials for review, then query the task, available_models and model_readiness before generating with a ready target model. Reuse the same asset ID later while it remains available; deletion, expiry or new copies can require an accessible original. Official H5 owner verification is a separate workflow, not a prerequisite for ordinary material review.

Create a session and complete H5 on the owner's phone

This section applies only to celebrities. Non-celebrities should skip owner liveness verification and proceed directly to material submission and review.

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\"}"

Use the actual channel returned by capability discovery. The response data includes session_id (also id), method=official_h5, status, created_at, expires_at, and h5_link (also verification_url) while the platform believes the link is usable. The owner must open the official link on their phone and complete authorization and liveness. The console entry /console/seedance-materials supports creating and privately copying the sensitive link to the owner's phone. Only your APIMaster key is entered; upstream AK/SK and BytedToken remain on the server.

APIMaster hosts the HTTPS callback; customers do not need a callback server. Omit callback_url: custom callbacks are rejected in this release. The callback validates a random association and the matching provider token, then queries GetVisualValidateResult on the server. Browser resultCode=10000 alone cannot create a verified group. Repeated callbacks do not create another group or upload assets.

curl --fail-with-body 'https://apimaster.ai/v1/seedance2/private-avatar/verifications/verification_PUBLIC_ID' -H "Authorization: Bearer $APIMASTER_KEY"

On completed, use the public group_id. Other states: creating, pending, failed (confirmed missing entitlement), expired, failed_unconfirmed (failure reported by a matched callback, not authoritative server proof), and submission_unknown (acceptance not confirmed). Transient query errors preserve state. Do not automatically create a new session after an error, timeout or an abandoned H5 flow. BytedToken has a 30-minute query lifetime; H5 is single-use. expires_at is the credential query deadline, not portrait authorization expiry. If the owner does not return via callback, the platform cannot independently know that the H5 link was consumed.

Idempotency-Key must contain 8–128 characters. Reuse it only for the same request; changed contents return 409. Creation is limited to three sessions per user per minute; upstream account limits still apply.

Submit materials through the shared endpoint and query each asset

Non-celebrities only need the material submission endpoint in this section; do not call the real-person verification endpoint first.

Unified materials and official real-person group materials both use POST /v1/seedance2/private-avatar/assets. The selected group and its channel determine the review flow. The legacy POST /v1/seedance2/private-avatar path invokes the same submission handler; it is not a separate owner-verification endpoint. POST /uploads only hosts source files and does not create upstream assets or complete verification.

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"}]}'

Upload accepts JPEG/PNG up to 10 MB. It returns upload_id, sensitive signed url, url_expires_at and delete_after. An authorized private store with a short-lived downloadable URL is also supported. Only use an explicitly authorized owner's photo.

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"

POST /uploads hosts the original; POST /assets submits materials for review. Ordinary groups use unified_virtual. Generate only when the target model is ready; new photos in an official real_person group still require same-person review. Partial success retains accepted assets. For an unconfirmed submission, keep the original task and asset IDs, query their status, and do not automatically upload again.

Quote, generate and download

Video generation is billed by the selected model and channel. Call /v1/videos/quote and confirm your budget before submitting. A quote is an estimate, not a guaranteed maximum charge.

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}'

Generation pins the compatible channel/account/project; incompatible asset combinations or explicit channel selections are rejected. Approved portraits can be reused across the four models only within compatible upstream context and each model's input limits. SD2.0 variants retain 4–15 seconds and their reference limits; SD2.5 supports 4–30 seconds, more references and its own editing parameters. See each model's existing protocol for resolution and supported roles.

Real-portrait generation requires an idempotency key and persists a separate video_request_* receipt and task_* ID before submission. X-Seedance-Request-Id identifies the receipt. Replays return 202 with the original receipt; they do not submit or charge again. Automatic POST retries are disabled for real-portrait generation. Quote, precharge, settlement and billing receipts otherwise use the existing system.

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

An uncertain receipt or task 404 is not permission to retry a paid task. Download after confirmed success; refunds follow actual existing billing receipts and failure handling.

Privacy, deletion and costs

Signed original URLs last one hour and permit access to their holders. Access to hosted originals stops after 24 hours; deletion completes within approximately 25 hours. DELETE /uploads/{upload_id} deletes only your hosted original. An upstream asset is separate. DELETE /assets/{asset_id} removes the APIMaster entry and uses upstream deletion where supported; where upstream deletion is unavailable, only the APIMaster mapping is removed and upstream deletion is not promised. Delete all assets before DELETE /groups/{group_id}. Removing an original before review may break upstream download; deleting an approved asset prevents future references but does not automatically delete generated videos.

Do not log H5 links, signed URLs or callback credentials. No biometric template is added. Authorization validity is governed by the owner's permission and upstream rules, not by the 30-minute authentication credential lifetime. No unsupported authorization-revocation API is promised.

Checked 2026-10-07: official Volcengine guidance describes verification as temporarily free. Actual channel charges for session creation, verification, same-person review, upload, storage and asset management remain unverified. This implementation adds no asset billing deduction, which is not a promise of permanent upstream free service. No entitlement package is automatically bought. The callback's billing flag is not an independently verified invoice.

HTTP 400/403/404/409/429/502/503 distinguish invalid input/callback, permissions, missing resources, not-ready or incompatible context, rate limits and uncertain upstream results. Session, review and video-request IDs provide safe trace references.

Official references, checked 2026-10-07: owner library, H5 sessions, result lookup, entitlements, assets, asset status, generation, model comparison.

Seedance idempotency and submission recovery

Unified virtual materials and automatic recovery

Create a virtual group without channel_id to reference compatible models through one asset:// ID. available_models, model_readiness and all_models_ready describe readiness. Approval by one service does not approve another. Poll the review task to refresh status; preparing missing copies requires an accessible original. Existing groups and official H5 assets retain their original binding restrictions.

Generation requires Idempotency-Key. Submission-stage fallback is possible only after an explicit rate rejection without a task ID. An accepted task ending with a confirmed account disablement, invalid credential or service failure may recover automatically once when a compatible service is available. Recovery retains the public task ID and frozen user tariff without a second generation reservation. Continue querying the original task and billing receipt.

Before recovery references materials, the target service needs compatible approved copies or must complete independent review. Approval is not transferable between services; official H5 verification is not copied between accounts. Parameter, moderation and copyright errors, timeouts, disconnections and uncertain acceptance do not qualify. Recovery is conditional. For manual resubmission, query the acceptance receipt first and use a new key only when new_submission_safe=true.