API Reference · Portrait API

Portrait API

通过 /portrait/ 复用 12 个火山 Action，管理真人和虚拟人像素材。

概述

Portrait API 用于创建 AIGC 虚拟人像组、发起 LivenessFace 真人 H5 认证、添加媒体素材、轮询素材状态，并把 asset://<id> 传给 Video Generation API。

Endpoint

$POST https://api.alltoken.ai/v1/portrait/?Action=CreateAsset&amp;Version=2024-01-01

Action	Version	用途
`CreateVisualValidateSession`	`2024-01-01`	创建真人 H5 活体认证
`GetVisualValidateResult`	`2024-01-01`	用 BytedToken 换 GroupId
`GetAssetGroup` / `ListAssetGroups` / `UpdateAssetGroup` / `DeleteAssetGroup`	`2024-01-01`	管理人像组
`CreateAsset` / `GetAsset` / `ListAssets` / `UpdateAsset` / `DeleteAsset`	`2024-01-01`	管理素材
`CreateAssetGroup`	`2024-01-01`	仅 AIGC 路径创建虚拟人像组

创建虚拟人像素材组。LivenessFace 真人组由 H5 认证自动创建。

Request JSON

1	{ "GroupType": "AIGC", "Name": "avatar-001", "Title": "Avatar 001" }

每客户最多 50 个 active groups。

向指定 GroupId 添加公开媒体 URL，AssetType 可为 Image、Video 或 Audio。

Request JSON

1	{ "GroupId": "group-xxx", "URL": "https://example.com/portrait.png", "AssetType": "Image", "Name": "front-face" }

创建真人认证会话，返回 H5Link 和 BytedToken。

Request JSON

1	{ "CallbackURL": "https://www.example.com/portrait/callback", "ProjectName": "default" }

客户后端收到 resultCode=10000 后，用 BytedToken 查询 GroupId。未完成时可能返回 ValidatePending。

素材对象包含 Id、GroupId、Name、AssetType、Status、URL。Status 为 Processing、Active 或 Failed。

人像组对象包含 Id、Name、GroupType、ProjectName 和时间戳。DeleteAssetGroup 会立即释放配额。

所有 Get、List、Update、Delete Action 都按当前 API Key 所属客户隔离，跨租户访问会返回 Forbidden 或 not-found 风格错误。