Owner verification and portrait assets

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.

Official H5 adapters cover Volcengine Ark and BytePlus. Configured AK/SK credentials do not prove that the required API entitlement is enabled. The official entitlement table distinguishes console-only verification on the basic free tier from real-person Assets API support on free advanced Entry. Ask the channel operator to confirm the account's API entitlement. APIMaster does not automatically activate entitlements, accept agreements or purchase packages.

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 live_acceptance. Configured asset credentials do not prove account entitlement.

Model	Official Ark / BytePlus H5 integration	APIMart / APIB	VideoFee	Other integrations
seedance-2.0	Adapter implemented; account, project, model routing and entitlement must be available	Material library; no real-owner H5 exposed	Channel material review; no official owner H5	Unverified
seedance-2.0-fast	Same conditions	Same limitation	Same limitation	Unverified
seedance-2.0-mini	Same conditions	Same limitation	Same limitation	Unverified
seedance-2.5	Same conditions	Same limitation	Same limitation	Unverified

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

Channel material review (VideoFee)

Set APIMASTER_KEY to your APIMaster key and APIMASTER_CHANNEL_ID to an available channel ID from capability discovery. When capabilities returns method=channel_material_review, use the channel material workflow. It is distinct from official_h5: an Active channel asset does not prove official owner liveness verification. Only submit explicitly authorized portrait photos.

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

Set APIMASTER_CHANNEL_ID from capability discovery and use the returned public group data.id for controlled upload and asset submission below. group_type=channel_portrait denotes a platform-managed group, not an official real-person GroupId. Use purpose=ordinary for ordinary assets. These explicit purposes apply to VideoFee integrations supporting this workflow. Requests omitting purpose retain their existing behavior; historical groups are not reclassified as verified owners.

The channel runs background material review without an owner H5 link. Asset responses include verification_method=channel_material_review, owner_verified=false, material_purpose and review.scope_model. Only Active assets may generate. Unconfirmed cross-model compatibility is rejected without switching routes or repeating uploads. Portrait submission and generation require Idempotency-Key; generation keeps existing quote, reservation and settlement rules. Query uncertain submissions before retrying. Deletion removes the APIMaster mapping; no upstream deletion is promised where the channel has not documented that operation.

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

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

Ordinary and virtual materials, official real-person group materials, and channel portrait materials all 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"

Submitting is not approval. New photos in an official real_person group undergo upstream same-person review. A channel_portrait group uses channel material review, whose result is not proof of official same-person comparison or owner liveness. Only Active assets may generate; Processing, Pending and Failed cannot. A partially accepted batch retains accepted IDs. A timed-out submission returns submission_unknown; query existing assets and ask support to reconcile items without a confirmed upstream ID. Never infer an asset ID from a filename or review task. POST /groups creates virtual groups by default. On VideoFee, explicit purpose=ordinary or channel_portrait creates the corresponding platform-managed material group. None of these manually created groups proves official owner verification; old groups are not upgraded retroactively.

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. Originals reside in a private directory with 0600 files; access stops after 24 hours and hourly cleanup removes them 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; for VideoFee, upstream deletion is not available in the documented integration. 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. The deployment requires the documented proxy logging exclusions. 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.