Active, reference it as asset://<asset ID> when you create a video generation task.
Actions
All management actions share one endpoint and are selected byAction:
BaseUrlishttps://api-vip.apigo.ai. See Usage overview.Versionis always2024-01-01.- Request and response fields are case-sensitive, for example
URL,AssetType,GroupId,Status. ProjectNameis optional. Passdefaultor omit it.
Authentication
Signing parameters:
Example request:
X-Dateis UTC inYYYYMMDDTHHMMSSZformat and must be within 15 minutes of server time.- The signature covers the exact request body bytes sent. Changing the body,
Action,HostorX-Dateafter signing requires a new signature.
Signing algorithm
<YYYYMMDD> is the date part of the same X-Date. Use the API key as SK directly, without any prefix.
Signing code
- Go (Volcengine SDK)
- Python (standard library)
The Volcengine Go SDK signs requests automatically in For other actions, change
DoCall. Requires Go 1.22 or later.main.go
Action and the request body.X-Date, X-Content-Sha256 and Authorization with the code above, then send the identical request body.
Response format
On success, HTTP 200 with the payload inResult:
Result; the error is in ResponseMetadata.Error:
Asset status
After
CreateAsset returns an asset ID, the asset is usually Processing. Poll GetAsset until it becomes Active before using it. Processing time varies.
Real-person assets
There are two asset group types:
To generate videos with a real person’s portrait as reference, the person must first complete liveness verification, then their photos are imported into the real-person group created by that verification:
- Call CreateVisualValidateSession to get
BytedTokenandH5Link. - The person opens
H5Linkin a mobile browser and completes the face scan. - Poll GetVisualValidateResult until it returns
GroupId. - Call CreateAsset with that real-person group ID as
GroupIdand the person’s photo asURL. - Once GetAsset returns
Active, reference it in generation tasks asasset://<asset ID>.
- Each successful verification creates a new real-person group with an empty name. Use UpdateAssetGroup to set a name and description.
- A real-person group only accepts photos of the verified person. If the photo does not match, the asset status becomes
FailedwithError.CodeFaceMismatch. - To query real-person groups or their assets, pass
LivenessFaceasFilter.GroupTypetoListAssetGroups/ListAssets. - Real-person groups can be deleted with DeleteAssetGroup, which also deletes their assets.
Pagination
ListAssetGroups and ListAssets support two pagination modes. Use only one per request.
NextToken pagination (default)
- No
NextTokenin the response means you have reached the last page. - Keep
Filter,SortByandSortOrderunchanged while paging, and passNextTokenback as-is. - This mode does not return
TotalCount.
Page number pagination
PageNumberandPageSizemust be passed together and cannot be combined withMaxResultsorNextToken.- The response includes
TotalCount,PageNumberandPageSize. - Depth limit:
PageNumber × PageSize ≤ 10000forListAssetGroupsand≤ 20000forListAssets. Exceeding it returns400 InvalidParameter. Use NextToken pagination to go deeper.
Error codes
An import failure can surface in two ways:
CreateAsset returns an error directly, or creation succeeds and GetAsset later returns Status=Failed.