Guides · Portrait

Portrait

Onboard virtual or real-person portraits and reference them in Seedance 2.0 video generation.

Overview

Portrait turns a virtual spokesperson or a verified real person into reusable assets for video generation. The output of the onboarding flow is an asset_id, which Seedance 2.0 can consume as asset://<asset-id> in multimodal input.

AllToken exposes the Portrait backend through the same API key model as the rest of the platform. The Portrait API follows Volcengine-style Action + Version routing with JSON request bodies.

Choose your path

Choose the onboarding path based on whether the person is fictional or a real person who must complete liveness verification.

Decision tree for choosing between the AIGC virtual portrait path and the LivenessFace real-person portrait path. — Choose AIGC for virtual or fictional portraits; choose LivenessFace when a real person must complete H5 liveness verification.

AIGC virtual portrait flow

Use the AIGC path for fully fictional or brand-owned virtual presenters. Create a group, register media, then poll until the asset is active.

Swimlane sequence diagram showing CreateAssetGroup, media upload, CreateAsset, GetAsset polling, and asset_id readiness for the AIGC virtual portrait flow. — AIGC virtual portraits create the group directly, upload media by public URL, then poll the asset until it is ready for Seedance 2.0.

CreateAssetGroup requires GroupType=AIGC and Name.
CreateAsset accepts AssetType: Image, Video, or Audio.

Wait for UpstreamStatus=Active before using the asset. After CreateAsset, Volcengine runs compliance checks (style review for AIGC, liveness verification for real-person). Poll GetAsset(Id) roughly every 3 seconds (up to ~60 seconds) until Result.UpstreamStatus turns Active. Calling Seedance with an asset still in Processing will be rejected.

LivenessFace real-person flow

Use LivenessFace when the portrait represents a real person. Your backend creates a visual validation session, your frontend opens the returned H5Link on the user's phone, and your backend exchanges BytedToken for GroupId after successful verification.

Swimlane sequence diagram showing CreateVisualValidateSession, H5Link scan, CallbackURL, GetVisualValidateResult, and the shared CreateAsset polling tail for LivenessFace. — LivenessFace adds the H5 scan and callback before returning a verified GroupId; after that, asset creation follows the same tail as AIGC.

BytedToken and H5Link are valid for about 120 seconds.
ValidatePending means the H5 scan is not finished yet.

Use asset_id in Seedance 2.0

Warning

Only seedance-2.0 and seedance-2.0-fast support asset://. seedance-1.5-pro does not — passing an asset:// URL to it will be rejected upstream.

After GetAsset returns UpstreamStatus=Active, pass the Portrait asset into Seedance 2.0 using an asset:// URL. The same pattern works for AIGC and LivenessFace assets.

cURL: use asset_id in Seedance 2.0

1	curl https://api.alltoken.ai/v1/videos/generations -H "Authorization: Bearer $ALLTOKEN_API_KEY" -H "Content-Type: application/json" -d '{
2	"model": "seedance-2.0",
3	"prompt": "A confident keynote speaker on stage, cinematic 4K",
4	"ratio": "16:9",
5	"duration": 5,
6	"resolution": "720p",
7	"content": [
8	{ "type": "image_url", "image_url": { "url": "asset://asset-20260318035710-xxxxx" }, "role": "first_frame" }
9	]
10	}'

Quotas and limits

Maximum 50 active groups per customer. DeleteAssetGroup releases quota immediately.
Maximum 50 assets per group.
Name is limited to 50 characters.

Two ways to register media into Portrait, depending on whether you have a CDN / public host:

With CDN / public host: POST /v1/portrait/?Action=CreateAsset with URL in the JSON body (URL must be publicly reachable by Volcengine).
Without CDN: POST /v1/portrait/upload as multipart/form-data with fields file + GroupId. The gateway uploads to R2 and auto-registers with Volcengine.

multipart limits: file types image/jpeg / image/png / image/webp; max size 10 MB; counts against the same 50-asset quota as CreateAsset.

multipart upload (cURL)

1	curl https://api.alltoken.ai/v1/portrait/upload -H "Authorization: Bearer $ALLTOKEN_API_KEY" -F "GroupId=group-20260318035710-xxxxx" -F "file=@./portrait.jpg"

All 12 Actions

The /v1/portrait/ endpoint multiplexes 12 Actions via the ?Action=... query (Volcengine Action protocol style).

Action	Purpose	Path
`CreateAssetGroup`	Create AIGC virtual portrait group	AIGC only
`GetAssetGroup`	Get group details	Both
`ListAssetGroups`	List groups (filter by `GroupType`)	Both
`UpdateAssetGroup`	Rename / update group meta	Both
`DeleteAssetGroup`	Delete group (releases quota)	Both
`CreateAsset`	Register asset by URL	Both
`GetAsset`	Get asset status / metadata	Both
`ListAssets`	List assets in a group	Both
`UpdateAsset`	Rename asset	Both
`DeleteAsset`	Delete asset (releases quota)	Both
`CreateVisualValidateSession`	Start H5 face-scan session	LivenessFace only
`GetVisualValidateResult`	Fetch `GroupId` after scan	LivenessFace only

Complete API reference: Portrait API reference (request / response fields, examples per Action).

Errors

Code	When it appears	What to do
`InvalidParameter`	Wrong `GroupType`, invalid `AssetType`, or malformed body	Fix the request body and retry.
`AIGCNotAvailable`	AIGC group creation is not enabled for the account	Contact AllToken support or use LivenessFace.
`ValidatePending`	H5 scan is not finished yet	Wait briefly, then retry before the 120-second token window expires.
`InvalidToken`	`BytedToken` is unknown or not owned by the API key	Create a new validation session.
`TokenExpired`	`BytedToken` has expired	Create a new validation session and ask the user to scan again.
`QuotaExceeded`	Group or asset quota is full	Delete unused groups or assets, then retry.
`Forbidden`	Cross-customer access to `GroupId` / `AssetId` owned by another customer	Use only IDs returned to your own API key. Existence is intentionally hidden.
`InvalidParameter`	`CreateAssetGroup` with `GroupType=LivenessFace`	LivenessFace groups are auto-created by the H5 scan flow only; do not call `CreateAssetGroup` for them.