Guides · 人像素材

人像素材

接入虚拟人或真人 Portrait，并在 Seedance 2.0 视频生成中通过 asset:// 引用。

概述

Portrait 用于把虚拟代言人或已完成真人活体认证的人像沉淀成可复用素材。流程最终产物是 asset_id，Seedance 2.0 可通过 asset://<asset-id> 作为多模态输入引用。

Portrait API 采用火山风格的 Action + Version + JSON body 协议，并复用 AllToken API Key 鉴权。

选择接入路径

根据人物是虚构形象还是真人，选择 AIGC virtual portrait 或 LivenessFace real-person 路径。

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

AIGC 路径用于虚拟或品牌自有形象：创建素材组，注册媒体素材，然后轮询直到素材可用。

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.

使用素材前必须等待 UpstreamStatus=Active。CreateAsset 后，Volcengine 会执行合规检查。建议每 3 秒轮询一次 GetAsset(Id)，最多约 60 秒，直到 Result.UpstreamStatus 变为 Active。仍处于 Processing 的素材传给 Seedance 会被上游拒绝。

LivenessFace real-person flow

LivenessFace 用于真人人像。后端创建 visual validation session，前端在用户手机打开 H5Link，认证成功后后端用 BytedToken 换取 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

警告

仅 seedance-2.0 和 seedance-2.0-fast 支持 asset://。seedance-1.5-pro 不支持；传入 asset:// URL 会被上游拒绝。

当 GetAsset 返回 UpstreamStatus=Active 后，用 asset:// URL 把 Portrait 素材传给 Seedance 2.0。AIGC 与 LivenessFace 素材使用同一模式。

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.

根据你是否已有 CDN / 公网托管，可用两种方式注册 Portrait 素材：

有 CDN / 公网托管：调用 POST /v1/portrait/?Action=CreateAsset，在 JSON body 中传 URL（URL 必须能被 Volcengine 公网访问）。
无 CDN：调用 POST /v1/portrait/upload，使用 multipart/form-data 字段 file + GroupId。网关会上传到 R2 并自动注册到 Volcengine。

multipart 限制：文件类型 image/jpeg / image/png / image/webp；最大 10 MB；与 CreateAsset 共享同一个 50 素材配额。

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 个 Action

/v1/portrait/ 通过 ?Action=... query 复用 12 个 Action（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

完整 API 参考：Portrait API reference（每个 Action 的请求 / 响应字段与示例）。

错误处理

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.