API Reference · Portrait API

Portrait API

12 Actions multiplexed via /portrait/ using the Volcengine Action protocol.

Overview

The Portrait API manages reusable human or virtual portrait assets. It is not a pure REST resource tree; it follows a Volcengine-style protocol where every request is POST /portrait/?Action=... with Version=2024-01-01 and a JSON body.

Use it to create AIGC portrait groups, run LivenessFace H5 validation for real people, add media assets by public URL, poll asset status, and then pass asset://<id> into Video Generation API.

Endpoint and protocol

Endpoint

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

Auth: Authorization: Bearer <alltoken_api_key>
Content-Type: application/json
Body limit: 1 MB
Success and upstream errors: HTTP can be 200; check ResponseMetadata.Error for upstream errors.
Region / Service: cn-beijing / ark
ProjectName: optional, defaults to default.

12 Actions reference

Action	Version	Purpose	Body style
`CreateVisualValidateSession`	`2024-01-01`	Create real-person H5 liveness session	JSON body
`GetVisualValidateResult`	`2024-01-01`	Exchange `BytedToken` for `GroupId`	JSON body
`GetAssetGroup`	`2024-01-01`	Read one portrait group	JSON body
`ListAssetGroups`	`2024-01-01`	List customer-scoped groups	JSON body
`UpdateAssetGroup`	`2024-01-01`	Rename or describe a group	JSON body
`DeleteAssetGroup`	`2024-01-01`	Delete a group and release quota	JSON body
`CreateAsset`	`2024-01-01`	Add media URL into a group	JSON body
`GetAsset`	`2024-01-01`	Read one asset and poll status	JSON body
`ListAssets`	`2024-01-01`	List customer-scoped assets	JSON body
`UpdateAsset`	`2024-01-01`	Update asset metadata	JSON body
`DeleteAsset`	`2024-01-01`	Delete an asset	JSON body
`CreateAssetGroup`	`2024-01-01`	Create AIGC virtual portrait group	JSON body

CreateAssetGroup (AIGC only)

Creates a virtual portrait group. LivenessFace real-person groups are created by the H5 validation flow, not by this Action.

Request JSON

1	{
2	"GroupType": "AIGC",
3	"Name": "avatar-001",
4	"Title": "Avatar 001",
5	"Description": "Virtual presenter"
6	}

Result JSON

1	{
2	"Id": "group-20260518163348-xtzxl"
3	}

Errors include MissingParameter, InvalidParameter, QuotaExceeded, and AIGCNotAvailable. Each customer can keep up to 50 active groups.

CreateAsset

Adds a public media URL to a portrait group. Volcengine accepts URLs, not binary uploads, so upload files to your own OSS/CDN first.

Request JSON

1	{
2	"GroupId": "group-20260331145705-xxxxx",
3	"URL": "https://example.com/portrait.png",
4	"AssetType": "Image",
5	"Name": "front-face"
6	}

Result JSON

1	{
2	"Id": "asset-20260318035710-xxxxx"
3	}

After creation, call GetAsset until Status is Active or Failed.

CreateVisualValidateSession (LivenessFace)

Creates a real-person validation session and returns an H5 link for the user's phone.

Request JSON

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

Result JSON

1	{
2	"BytedToken": "20260516170000EXAMPLE",
3	"H5Link": "https://h5-v2.kych5.com?...",
4	"CallbackURL": "https://www.example.com/portrait/callback"
5	}

H5Link and BytedToken are short-lived, roughly 120 seconds.

GetVisualValidateResult (LivenessFace)

After your backend receives resultCode=10000 on CallbackURL, call this Action to fetch the generated real-person GroupId.

Request JSON

1	{
2	"BytedToken": "20260516170000EXAMPLE",
3	"ProjectName": "default"
4	}

Result JSON

1	{
2	"GroupId": "group-20260516170001-example"
3	}

If verification is not complete, the response can include ResponseMetadata.Error.Code=ValidatePending.

GetAsset / ListAssets / UpdateAsset / DeleteAsset

Asset Actions are customer-scoped by API key. GetAsset returns an AssetItem with Id, GroupId, Name, AssetType, Status, URL, timestamps, and optional FailedReason.

Status: Processing, Active, or Failed.
AssetType: Image, Video, or Audio.
ListAssets supports filters such as Filter.GroupType, Filter.Name, Filter.GroupIds, and Filter.Statuses.
ListAssets.URL can expire; call GetAsset when you need the latest URL.

GetAssetGroup / ListAssetGroups / UpdateAssetGroup / DeleteAssetGroup

Group Actions manage AIGC and LivenessFace groups. A group item includes Id, Name, Title, Description, GroupType, ProjectName, and timestamps.

GroupType: AIGC for virtual groups, LivenessFace for H5-verified real-person groups.
ListAssetGroups supports Filter.GroupType, Filter.Name, Filter.GroupIds, PageNumber, and PageSize.
DeleteAssetGroup immediately releases the active-group quota.

Error codes

Code	Source	Meaning
`Unauthorized`	Gateway	Missing or invalid API key.
`Forbidden`	Gateway	The API key cannot access this group or asset.
`QuotaExceeded`	Gateway	Customer group or asset quota is full.
`RateLimitExceeded`	Gateway	Too many requests.
`TokenExpired`	Upstream	`BytedToken` exceeded its 120-second window.
`InvalidToken`	Upstream	`BytedToken` is invalid or not owned by the key.
`ValidatePending`	Gateway	The H5 validation flow has not produced `GroupId` yet.
`AIGCNotAvailable`	Gateway	AIGC group creation is not enabled for this account.
`MissingParameter` / `InvalidParameter`	Gateway or upstream	Request body is missing required fields or has invalid values.

Multi-tenant isolation

AllToken maps upstream resources to the current customer and API key. Get, List, Update, and Delete Actions are scoped to resources owned by the same customer. Cross-tenant access returns Forbidden or a not-found style error.

Customer-visible names are mapped internally; do not rely on upstream raw names for authorization or tenancy checks.

Try in Interactive Explorer

The interactive API explorer includes the OpenAPI surface for live request experiments. For the narrative onboarding flows, start with the Portrait guide.

Open Scalar Explorer →