Guides · 인물

인물

가상 인물 또는 검증된 실제 인물 Portrait 를 등록하고 Seedance 2.0 에서 asset:// 로 참조합니다.

개요

Portrait converts a virtual spokesperson or verified real person into reusable assets for video generation. The flow returns an asset_id, which Seedance 2.0 can consume as asset://<asset-id>.

The API uses Volcengine-style Action + Version routing with JSON request bodies.

경로 선택

인물이 가상인지, 실제 사용자 H5 생체 인증이 필요한지에 따라 경로를 선택합니다.

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 fictional or brand-owned characters: 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. Poll GetAsset(Id) roughly every 3 seconds, up to about 60 seconds, until Result.UpstreamStatus becomes Active. Seedance rejects assets still in Processing.

LivenessFace real-person flow

Use LivenessFace for a real person. Create a visual validation session, open H5Link on the user phone, then exchange BytedToken for GroupId.

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.

Seedance 2.0 에서 asset_id 사용

경고

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.

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

쿼터와 업로드

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 JSON body. The URL must be publicly reachable by Volcengine.
Without CDN: POST /v1/portrait/upload as multipart/form-data with file + GroupId. The gateway uploads to R2 and auto-registers with Volcengine.

multipart limits: image/jpeg / image/png / image/webp; max size 10 MB; shares 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"

전체 12 Actions

The /v1/portrait/ endpoint multiplexes 12 Actions via ?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.

오류

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.