Asset Library API Integration Guide (Volcengine Official Format)

This document describes the asset-library proxy API provided by api.aiide.com. The API follows the request and response conventions of the Volcengine Ark Universal API and is intended for downstream SDKs, agents, and script clients.

Features

✅ Supports asset-group (AssetGroup) and asset-file (Asset) management

✅ Supports AK/SK HMAC-SHA256 signature authentication and API Key Bearer authentication

❌ The current version does not provide digital-human liveness verification APIs (CreateVisualValidateSession and GetVisualValidateResult)

1. Endpoint

2. Protocol

3. Authentication

3.1 Method 1: AK/SK signature authentication

3.2 Method 2: API Key Bearer authentication

3.3 Using the Volcengine official SDK

4. Data isolation and resource model

5. Request and response format

6. Supported operations

7. Asset-group API details

8. Asset API details

9. Recommended integration flow

10. Differences from the official Volcengine API

1. Endpoint

Base URL:

https://api.aiide.com/v1/ark/asset/

Method: POST

URL format:

POST https://api.aiide.com/v1/ark/asset/?Action=<ActionName>&Version=2024-01-01

Fixed Parameters

Parameter	Fixed value	Required	Description
`Action`	See the operation list	Yes	URL query parameter that specifies the operation
`Version`	`2024-01-01`	Yes	API version; include it in every request
`Content-Type`	`application/json`	Yes	HTTP request header

Fixed response metadata values:

Service: ark

Region: cn-beijing

Note: Do not use another version number. The server generates response metadata using these fixed values.

2. Protocol

The asset-library API uses the Volcengine ARK Action protocol. All operations share the root path /v1/ark/asset/ and are dispatched by the Action query parameter and the fixed version Version=2024-01-01.

Standard request format:

Each Action in this document has its own API description, request structure, and response example.

3. Authentication

The asset library supports two authentication methods. Choose one; do not mix them in the same request.

3.1 Method 1: AK/SK Signature Authentication with the Volcengine Official SDK

Use case:

Asset-library Action APIs such as CreateAsset and ListAssets

Where to obtain credentials:

User API Management Portal → Access Credentials

Required headers:

Notes:

Requests are signed with HMAC-SHA256.

The X-Date and X-Content-Sha256 headers are required.

The signing method is fully compatible with the Volcengine official SDK (volcengine-go-sdk).

Asset access is isolated by the user associated with the access credentials.

See the official Volcengine documentation for signing-algorithm details.

3.2 Method 2: API Key Bearer Authentication

Use cases:

Asset-library Action APIs

Seedance video-generation task APIs

Where to obtain a token:

User API Management Portal → Token Management

Header format:

Characteristics:

✅ Simple integration with no complex signature calculation

✅ Asset space and usage statistics are isolated by the user associated with the API Key

✅ Supports platform-wide quota, group, and IP restrictions

Example:

3.3 Using the Volcengine Official SDK

The Volcengine official SDK points to open.volcengineapi.com by default. To use this service, change the endpoint and select one authentication method.

Using AK/SK Credentials (Recommended)

Do not include a trailing / in the Endpoint. The official universal SDK automatically appends / to the path. Configure it as .../asset; the actual request is sent to .../asset/. Configuring .../asset/ would produce a double slash and cause a 404 response.

The same rule applies to official SDKs in other languages: point endpoint or base_url to this service's /v1/ark/asset path, then configure AK/SK authentication or use the SDK interceptor mechanism to add the Authorization: Bearer <token> header.

4. Data Isolation and Resource Model

4.1 Resource Objects

The asset library contains two object types:

Object type	Description	Relationship
AssetGroup	Asset group	Organizes assets of the same kind
Asset	Asset file	Must belong to an asset group

4.2 Data-Isolation Rules

Isolation dimension:

User account associated with the API Key

Access rules:

✅ The same API Key can access every asset group and asset belonging to its associated user.

✅ With AK/SK signing, access is isolated by the user associated with the credentials.

❌ Different users cannot access one another's resources.

4.3 Asset-Group Configuration

Asset groups created through CreateAssetGroup always use this fixed configuration:

{
  "GroupType": "AIGC",
  "ProjectName": "default"
}

Notes:
Do not pass GroupType or ProjectName in the creation request; the server sets them automatically.
The current version does not support creating LivenessFace digital-human asset groups through CreateVisualValidateSession or GetVisualValidateResult.

4.4 Asset Status

After an asset is uploaded, the server maps the asset-provider status to the status visible to the current user:

Status	Description	Availability
`Processing`	The asset is still processing	Not yet available
`Active`	Asset processing is complete	Can be used in video-generation requests
`Failed`	Asset processing failed	The `Error` field in the response may contain the failure reason

4.5 Asset Reference Format

Use this standard format to reference an asset in a video-generation request:

asset://<asset_id>

Example:

{
  "image": "asset://asset-20260820105215-kqtAk"
}

Note: Whether a model supports a particular asset type depends on the configured asset provider and model capabilities.

5. Request and Response Format

5.1 Successful Response

HTTP status: 200 OK

Response body:

{
  "ResponseMetadata": {
    "RequestId": "request-id",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260821120000-abcde"
  }
}

Field descriptions:

Field	Type	Description
`ResponseMetadata`	Object	Response metadata
`ResponseMetadata.RequestId`	String	Unique request identifier
`ResponseMetadata.Action`	String	Operation name
`ResponseMetadata.Version`	String	API version
`ResponseMetadata.Service`	String	Service name, fixed as `ark`
`ResponseMetadata.Region`	String	Region, fixed as `cn-beijing`
`Result`	Object	Operation result data

5.2 Error Response

Response body:

{
  "ResponseMetadata": {
    "RequestId": "request-id",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "ResourceNotFound",
      "Message": "Asset does not exist"
    }
  },
  "Result": null
}

5.3 Error Codes

HTTP status	Error code	Description	Common cause
`400`	`InvalidParameter`	Invalid request parameters	A required request-body field is missing or a field value is invalid
`400`	`UnsupportedAction`	Unsupported operation	The `Action` value is not supported
`401`	`Unauthorized`	Authentication failed	The Bearer Token is invalid or the aggregation-user header is missing or invalid
`403`	`PermissionDenied`	Insufficient permissions	The resource belongs to another user or access is not allowed
`404`	`ResourceNotFound`	Resource does not exist	The requested asset group or asset does not exist
`500`	`InternalError`	Internal error	Server or asset-processing service failure

6. Supported Operations

The following Action operations are currently supported:

Asset-Group Operations

Action	Description
`CreateAssetGroup`	Create an asset group
`GetAssetGroup`	Get asset-group details
`ListAssetGroups`	List asset groups
`UpdateAssetGroup`	Update an asset group
`DeleteAssetGroup`	Delete an asset group

Asset Operations

Action	Description
`CreateAsset`	Create or upload an asset
`GetAsset`	Get asset details
`ListAssets`	List assets
`UpdateAsset`	Update an asset
`DeleteAsset`	Delete an asset

For detailed request parameters and response fields, refer to the Volcengine Ark Universal API documentation or request the detailed API specification from the platform provider.

7. Asset-Group API Details

7.1 CreateAssetGroup

Creates a new asset group.

Request example:

Request-body fields:

Field	Type	Required	Description
`Name`	string	Yes	Asset-group name; 1–64 characters
`Description`	string	No	Asset-group description; up to 300 characters

Successful response:

{
  "ResponseMetadata": {
    "RequestId": "req-20260821-001",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260821120000-abcde"
  }
}

7.2 ListAssetGroups

Lists the current user's asset groups with pagination.

Request example:

Request-body fields:

Field	Type	Required	Default	Description
`Filter.GroupIds`	string[]	No	-	Filter by a list of asset-group IDs
`Filter.Name`	string	No	-	Filter by asset-group name
`Filter.GroupType`	string	No	-	Filter by asset-group type, such as `AIGC`
`PageNumber`	integer	No	1	Page number, starting at 1
`PageSize`	integer	No	10	Items per page; maximum 100
`SortBy`	string	No	`CreateTime`	Sort field: `CreateTime` or `UpdateTime`
`SortOrder`	string	No	`Desc`	Sort direction: `Desc` or `Asc`

Successful response:

{
  "ResponseMetadata": {
    "RequestId": "req-20260821-002",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "TotalCount": 1,
    "Items": [
      {
        "Id": "group-20260821120000-abcde",
        "Name": "My asset group",
        "Description": "Stores digital-human portrait assets",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2026-08-21T12:00:00Z",
        "UpdateTime": "2026-08-21T12:00:00Z"
      }
    ],
    "PageNumber": 1,
    "PageSize": 20
  }
}

7.3 GetAssetGroup

Gets asset-group details.

Request example:

Field	Type	Required	Description
`Id`	string	Yes	Asset-group ID
`ProjectName`	string	No	Project name; must match the asset-group project

The successful response contains the group's Id, Name, Description, GroupType, ProjectName, CreateTime, and UpdateTime under Result.

7.4 UpdateAssetGroup

Updates an asset-group name or description.

Field	Type	Required	Description
`Id`	string	Yes	Asset-group ID
`Name`	string	No	New asset-group name; 1–64 characters
`Description`	string	No	New asset-group description; up to 300 characters

A successful response returns the asset-group Id under Result.

7.5 DeleteAssetGroup

Deletes an asset group.

Field	Type	Required	Description
`Id`	string	Yes	Asset-group ID
`ProjectName`	string	No	Project name; must match the asset-group project

A successful response returns an empty Result object.

8. Asset API Details

8.1 CreateAsset

Registers a public URL as an asset and returns its asset ID and initial status.

Field	Type	Required	Description
`Name`	string	Yes	Asset name; 1–64 characters
`URL`	string	Yes	Public asset URL
`AssetType`	string	Yes	Asset type; currently only `Image` is supported
`GroupId`	string	Yes	ID of the owning asset group

A successful response returns the asset Id under Result.

8.2 GetAsset

Gets asset details and current status.

Field	Type	Required	Description
`Id`	string	Yes	Asset ID

A successful response contains the asset's Id, Name, URL, AssetType, GroupId, Status, Moderation, CreateTime, UpdateTime, and ProjectName under Result.

8.3 ListAssets

Lists assets visible to the current user with pagination.

Field	Type	Required	Description
`Filter.GroupIds`	string[]	No	Filter by a list of asset-group IDs
`Filter.GroupType`	string	No	Filter by asset-group type; `AIGC` is currently supported
`Filter.Name`	string	No	Filter by asset name
`PageNumber`	integer	No	Page number, starting at 1; defaults to 1
`PageSize`	integer	No	Items per page; defaults to 10, maximum 100
`SortBy`	string	No	Sort by `CreateTime`, `UpdateTime`, or `GroupId`; defaults to `CreateTime`
`SortOrder`	string	No	`Desc` or `Asc`; defaults to `Desc`

The successful Result contains Items, TotalCount, PageNumber, and PageSize. Each item contains the asset fields returned by GetAsset.

8.4 UpdateAsset

Updates an asset name.

Field	Type	Required	Description
`Id`	string	Yes	Asset ID
`Name`	string	Yes	New asset name; 1–64 characters

A successful response returns the asset Id under Result.

8.5 DeleteAsset

Deletes an asset.

Field	Type	Required	Description
`Id`	string	Yes	Asset ID

A successful response returns an empty Result object.

9. Recommended Integration Flow

A typical digital-human asset flow is:

Use CreateAssetGroup to create an AIGC asset group.

Use CreateAsset to register a public URL in that group.

Record the returned asset_id.

Poll the asset status with GetAsset.

When the status becomes Active, use asset://<asset_id> in the video-generation request.

Call DeleteAsset when the asset is no longer needed, and call DeleteAssetGroup if necessary.

Simple polling example:

10. Differences from the Official Volcengine API

This API reuses the Volcengine Universal API Action names, field names, and response envelope, but it is this site's asset-library proxy rather than the official Volcengine asset library. Note the following:

✅ API Key Bearer authentication is supported.

✅ AK/SK HMAC-SHA256 signature authentication is supported.

✅ All APIs currently support only the POST method.

❌ CreateVisualValidateSession and GetVisualValidateResult are not currently supported.

📌 Created asset groups always use GroupType=AIGC and ProjectName=default.

📌 GetAssetGroup, UpdateAssetGroup, and DeleteAssetGroup use the request-body field Id.

📌 Successful CreateAssetGroup and CreateAsset responses use Result.Id.

📌 CreateAsset accepts only public URLs; Base64 and multipart file uploads are not supported.

📌 The returned URL is the original asset URL stored by this site and must not be treated as a short-lived presigned URL.

Asset Library API Integration Guide (Volcengine Official Format)

Features#

Contents#

1. Endpoint#

Fixed Parameters#

2. Protocol#

3. Authentication#

3.1 Method 1: AK/SK Signature Authentication with the Volcengine Official SDK#

3.2 Method 2: API Key Bearer Authentication#

3.3 Using the Volcengine Official SDK#

Using AK/SK Credentials (Recommended)#

4. Data Isolation and Resource Model#

4.1 Resource Objects#

4.2 Data-Isolation Rules#

4.3 Asset-Group Configuration#

4.4 Asset Status#

4.5 Asset Reference Format#

5. Request and Response Format#

5.1 Successful Response#

5.2 Error Response#

5.3 Error Codes#

6. Supported Operations#

Asset-Group Operations#

Asset Operations#

7. Asset-Group API Details#

7.1 CreateAssetGroup#

7.2 ListAssetGroups#

7.3 GetAssetGroup#

7.4 UpdateAssetGroup#

7.5 DeleteAssetGroup#

8. Asset API Details#

8.1 CreateAsset#

8.2 GetAsset#

8.3 ListAssets#

8.4 UpdateAsset#

8.5 DeleteAsset#

9. Recommended Integration Flow#

10. Differences from the Official Volcengine API#

Features

Contents

1. Endpoint

Fixed Parameters

2. Protocol

3. Authentication

3.1 Method 1: AK/SK Signature Authentication with the Volcengine Official SDK

3.2 Method 2: API Key Bearer Authentication

3.3 Using the Volcengine Official SDK

Using AK/SK Credentials (Recommended)

4. Data Isolation and Resource Model

4.1 Resource Objects

4.2 Data-Isolation Rules

4.3 Asset-Group Configuration

4.4 Asset Status

4.5 Asset Reference Format

5. Request and Response Format

5.1 Successful Response

5.2 Error Response

5.3 Error Codes

6. Supported Operations

Asset-Group Operations

Asset Operations

7. Asset-Group API Details

7.1 CreateAssetGroup

7.2 ListAssetGroups

7.3 GetAssetGroup

7.4 UpdateAssetGroup

7.5 DeleteAssetGroup

8. Asset API Details

8.1 CreateAsset

8.2 GetAsset

8.3 ListAssets

8.4 UpdateAsset

8.5 DeleteAsset

9. Recommended Integration Flow

10. Differences from the Official Volcengine API