Skip to main content
The asset library stores reference images, audio and videos for video generation. Once an asset is imported and its status is Active, reference it as asset://<asset ID> when you create a video generation task.

Actions

All management actions share one endpoint and are selected by Action:
  • BaseUrl is https://api-vip.apigo.ai. See Usage overview.
  • Version is always 2024-01-01.
  • Request and response fields are case-sensitive, for example URL, AssetType, GroupId, Status.
  • ProjectName is optional. Pass default or omit it.

Authentication

The asset library management API uses HMAC-SHA256 signing and does not accept Authorization: Bearer. The video generation API uses Bearer. Both use the same ApiGo API key.
Signing parameters: Example request:
  • X-Date is UTC in YYYYMMDDTHHMMSSZ format and must be within 15 minutes of server time.
  • The signature covers the exact request body bytes sent. Changing the body, Action, Host or X-Date after 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

The Volcengine Go SDK signs requests automatically in DoCall. Requires Go 1.22 or later.
main.go
For other actions, change Action and the request body.
curl cannot compute the signature. To use curl, compute 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 in Result:
On failure there is no 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:
  1. Call CreateVisualValidateSession to get BytedToken and H5Link.
  2. The person opens H5Link in a mobile browser and completes the face scan.
  3. Poll GetVisualValidateResult until it returns GroupId.
  4. Call CreateAsset with that real-person group ID as GroupId and the person’s photo as URL.
  5. Once GetAsset returns Active, reference it in generation tasks as asset://<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 Failed with Error.Code FaceMismatch.
  • To query real-person groups or their assets, pass LivenessFace as Filter.GroupType to ListAssetGroups / 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 NextToken in the response means you have reached the last page.
  • Keep Filter, SortBy and SortOrder unchanged while paging, and pass NextToken back as-is.
  • This mode does not return TotalCount.

Page number pagination

  • PageNumber and PageSize must be passed together and cannot be combined with MaxResults or NextToken.
  • The response includes TotalCount, PageNumber and PageSize.
  • Depth limit: PageNumber × PageSize ≤ 10000 for ListAssetGroups and ≤ 20000 for ListAssets. Exceeding it returns 400 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.