Volcano Ark Compatible API Reference

tokenhub provides an API surface compatible with the Volcano Ark interface format, so users can adapt to tokenhub without changing their existing Volcano calling conventions. All endpoints share a single entry point, distinguished by the Action query parameter. Responses follow the Volcano style (all ids in Result are Volcano ids).

Quick Start

Get AK/SK

Log in to the ai-tokenhub console, go to Token Management, select AK/SK, and click Issue.

• Access Key ID (AK): starts with pak
• Secret Key (SK): starts with psk
• Important: SK is shown only once when generated. Keep it safe.

General Notes

• Base URL: https://ai-tokenhub.com
• Entry point: POST /ark?Action=<OperationName>&Version=2024-01-01
• Authentication: All endpoints use tokenhub personal access credentials (AK/SK), passed via the Authorization header:

  Authorization: Bearer pak_XXX:psk_XXX

  The tenant that owns the credential is the calling tenant — no tenant ID is required in the request.
• Request body: application/json, Volcano-style PascalCase fields (GetModerationResult is the exception, using id/type).
• ProjectName field: Volcano interfaces commonly carry this field. The compatible surface ignores the supplied value and uses the platform-configured value (default) — optional.
• Common response envelope (except CreateVisualValidateSession and GetVisualValidateResult):
  • Success: {"ResponseMetadata": {RequestId, Action, Version, Service, Region}, "Result": {...}}
  • Failure: {"ResponseMetadata": {...}, "ResponseError": {"Code": "...", "Message": "..."}}
  • ResponseMetadata fields: RequestId (request identifier), Action (operation name), Version (2024-01-01), Service (ark), Region (cn-beijing).
• Status enum (asset Status): Active (ready), Processing (in progress), Failed (failed).
• About ids: Id/GroupId in responses are Volcano ids (asset group group-..., asset Asset-...), which can be used directly as inputs to subsequent endpoints, forming a closed loop.

---

1. Get Real-Person Verification H5 Link

POST https://ai-tokenhub.com/ark?Action=CreateVisualValidateSession&Version=2024-01-01

Get the real-person verification H5 link. A successful response to this endpoint is NOT wrapped in the ResponseMetadata/Result envelope — it returns the fields below directly.

Request

Field	Type	Required	Description
CallbackURL	string	Yes	Accessible URL to redirect to after verification
ProjectName	string	No	Project name of the resource (ignored, uses configured default)

Response (returned directly, no envelope)

Field	Type	Description
BytedToken	string	Verification token
H5Link	string	H5 verification link
CallbackURL	string	Callback URL

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=CreateVisualValidateSession&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://www.example.com/callback","ProjectName":"default"}'

Response example

{
  "BytedToken": "bt_abc123def456",
  "H5Link": "https://ark.volcengine.com/region:c",
  "CallbackURL": "https://www.example.com/callback"
}

---

2. Get Real-Person Verification Result

POST https://ai-tokenhub.com/ark?Action=GetVisualValidateResult&Version=2024-01-01

Use the BytedToken returned by CreateVisualValidateSession to query the real-person verification result, which returns a Volcano asset group id. A successful response to this endpoint is NOT wrapped in the ResponseMetadata/Result envelope — it returns the fields below directly (consistent with Volcano's interface for this endpoint, same as CreateVisualValidateSession). When real-person verification is not yet complete, GroupId is an empty string and the caller can keep polling.

Request

Field	Type	Required	Description
BytedToken	string	Yes	Verification token returned by CreateVisualValidateSession

Response (returned directly, no envelope)

Field	Type	Description
GroupId	string	Volcano asset group id (group-...); empty string when verification is not complete

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=GetVisualValidateResult&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"202603311449168C23BA26xxxxxxxxxxxxx"}'

Response example

{
  "GroupId": "group-20260331145705-xxxxx"
}

---

3. Create Virtual Asset Group

POST https://ai-tokenhub.com/ark?Action=CreateAssetGroup&Version=2024-01-01

Request

Field	Type	Required	Description
Name	string	Yes	Asset group name
Description	string	No	Asset group description
GroupType	string	Yes	Asset group type; only AIGC is currently supported
ProjectName	string	No	Ignored, uses configured default

Response (Result field)

Field	Type	Description
Id	string	Asset group id (Volcano format group-...)

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Name":"test","Description":"test","GroupType":"AIGC","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {
    "RequestId": "20260709123000000000000000000000",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-2026abc123-def456"
  }
}

---

4. List Asset Groups

POST https://ai-tokenhub.com/ark?Action=ListAssetGroups&Version=2024-01-01

Request

Field	Type	Required	Description
Filter.Name	string	No	Fuzzy name match
Filter.GroupType	string	No	Asset group type (AIGC)
PageNumber	int	Yes	Page number, starting from 1
PageSize	int	Yes	Page size
SortBy	string	No	Ignored (sorting not supported)
SortOrder	string	No	Ignored
ProjectName	string	No	Ignored

Response (Result field)

Field	Type	Description
TotalCount	int	Total count
Items	array	Asset group list, see below
PageNumber	int	Current page number
PageSize	int	Page size

Items element fields: Id (Volcano group id), Name, Description, GroupType, CreateTime, UpdateTime (RFC3339).

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Filter":{"Name":"test","GroupType":"AIGC"},"PageNumber":1,"PageSize":10}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"ListAssetGroups","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "TotalCount": 1,
    "Items": [
      {
        "Id": "group-2026abc123-def456",
        "Name": "test",
        "Description": "test",
        "GroupType": "AIGC",
        "CreateTime": "2026-07-09T12:00:00Z",
        "UpdateTime": "2026-07-09T12:00:00Z"
      }
    ],
    "PageNumber": 1,
    "PageSize": 10
  }
}

---

5. Get Asset Group Detail

POST https://ai-tokenhub.com/ark?Action=GetAssetGroup&Version=2024-01-01

Request

Field	Type	Required	Description
Id	string	Yes	Asset group id (Volcano format group-...)
ProjectName	string	No	Ignored

Response (Result field)

Field	Type	Description
Id	string	Volcano group id
Name	string	Name
Description	string	Description
GroupType	string	Type
CreateTime	string	Creation time (RFC3339)
UpdateTime	string	Update time (RFC3339)

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=GetAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-2026abc123-def456","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"GetAssetGroup","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "Id": "group-2026abc123-def456",
    "Name": "test",
    "Description": "test",
    "GroupType": "AIGC",
    "CreateTime": "2026-07-09T12:00:00Z",
    "UpdateTime": "2026-07-09T12:00:00Z"
  }
}

---

6. Update Asset Group

POST https://ai-tokenhub.com/ark?Action=UpdateAssetGroup&Version=2024-01-01

Only Description can be modified currently. Passing a Name different from the current value returns 400 UnsupportedField.

Request

Field	Type	Required	Description
Id	string	Yes	Asset group id
Name	string	No	Not supported (a different value returns UnsupportedField)
Description	string	No	New description
ProjectName	string	No	Ignored

Response (Result field)

Field	Type	Description
Id	string	Volcano group id

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=UpdateAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-2026abc123-def456","Description":"updated","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"UpdateAssetGroup","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "Id": "group-2026abc123-def456"
  }
}

---

7. Delete Asset Group

POST https://ai-tokenhub.com/ark?Action=DeleteAssetGroup&Version=2024-01-01

Synchronously deletes the resource on the Volcano side.

Request

Field	Type	Required	Description
Id	string	Yes	Asset group id
ProjectName	string	No	Ignored

Response: Result is an empty object {}.

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=DeleteAssetGroup&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-2026abc123-def456","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"DeleteAssetGroup","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {}
}

---

8. List Assets

POST https://ai-tokenhub.com/ark?Action=ListAssets&Version=2024-01-01

Request

Field	Type	Required	Description
Filter.GroupIds	[]string	No	List of asset group ids; supports cross-group queries
Filter.GroupType	string	No	Asset group type
Filter.Statuses	[]string	No	Status filter (Active/Processing/Failed)
Filter.Name	string	No	Fuzzy name match
PageNumber	int	Yes	Page number
PageSize	int	Yes	Page size
SortBy / SortOrder	string	No	Ignored
ProjectName	string	No	Ignored

Response (Result field)

Field	Type	Description
TotalCount	int	Total count
Items	array	Asset list, see below
PageNumber	int	Current page number
PageSize	int	Page size

Items element fields: Id (Volcano asset id), Name, URL (accessible asset address), GroupId (Volcano group id), AssetType (Image/Video/Audio), Status (Active/Processing/Failed), Error.Code/Error.Message (populated on failure, empty on success), ProjectName, CreateTime, UpdateTime.

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=ListAssets&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Filter":{"GroupIds":["group-2026abc123-def456"],"GroupType":"AIGC"},"PageNumber":1,"PageSize":10}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"ListAssets","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "TotalCount": 1,
    "Items": [
      {
        "Id": "Asset-2026abc123-def456",
        "Name": "test",
        "URL": "https://example.com/image.jpg",
        "GroupId": "group-2026abc123-def456",
        "AssetType": "Image",
        "Status": "Active",
        "Error": {"Code": "", "Message": ""},
        "ProjectName": "default",
        "CreateTime": "2026-07-09T12:00:00Z",
        "UpdateTime": "2026-07-09T12:00:00Z"
      }
    ],
    "PageNumber": 1,
    "PageSize": 10
  }
}

---

9. Upload Asset

POST https://ai-tokenhub.com/ark?Action=CreateAsset&Version=2024-01-01

Synchronous upload: the response returns the Volcano asset id directly (no polling/backfill needed). URL must be a publicly accessible address; otherwise registration on the Volcano side will fail.

Request

Field	Type	Required	Description
GroupId	string	Yes	Asset group id
URL	string	Yes	Publicly accessible address of the asset
Name	string	Yes	Asset name
AssetType	string	Yes	Asset type (Image/Video/Audio)
ProjectName	string	No	Ignored

Response (Result field)

Field	Type	Description
Id	string	Volcano asset id (Asset-...)

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=CreateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"GroupId":"group-2026abc123-def456","URL":"https://example.com/image.jpg","Name":"test","AssetType":"Image","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"CreateAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "Id": "Asset-2026abc123-def456"
  }
}

---

10. Get Asset Detail

POST https://ai-tokenhub.com/ark?Action=GetAsset&Version=2024-01-01

Request

Field	Type	Required	Description
Id	string	Yes	Asset id (Volcano format Asset-...)
ProjectName	string	No	Ignored

Response (Result field)

Field	Type	Description
Id	string	Volcano asset id
Name	string	Name
URL	string	Accessible asset address
GroupId	string	Owning Volcano group id
AssetType	string	Type
Status	string	Active/Processing/Failed
Error.Code	string	Failure error code (empty on success)
Error.Message	string	Failure error message (empty on success)
ProjectName	string	Project name
CreateTime	string	Creation time (RFC3339)
UpdateTime	string	Update time (RFC3339)

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=GetAsset&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Id":"Asset-2026abc123-def456","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"GetAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "Id": "Asset-2026abc123-def456",
    "Name": "test",
    "URL": "https://example.com/image.jpg",
    "GroupId": "group-2026abc123-def456",
    "AssetType": "Image",
    "Status": "Active",
    "Error": {"Code": "", "Message": ""},
    "ProjectName": "default",
    "CreateTime": "2026-07-09T12:00:00Z",
    "UpdateTime": "2026-07-09T12:00:00Z"
  }
}

---

11. Update Asset

POST https://ai-tokenhub.com/ark?Action=UpdateAsset&Version=2024-01-01

Request

Field	Type	Required	Description
Id	string	Yes	Asset id
Name	string	No	New name
ProjectName	string	No	Ignored

Response (Result field)

Field	Type	Description
Id	string	Volcano asset id

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=UpdateAsset&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Id":"Asset-2026abc123-def456","Name":"test-renamed","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"UpdateAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "Id": "Asset-2026abc123-def456"
  }
}

---

12. Delete Asset

POST https://ai-tokenhub.com/ark?Action=DeleteAsset&Version=2024-01-01

Request

Field	Type	Required	Description
Id	string	Yes	Asset id
ProjectName	string	No	Ignored

Response: Result is an empty object {}.

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=DeleteAsset&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"Id":"Asset-2026abc123-def456","ProjectName":"default"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"DeleteAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {}
}

---

13. Get Moderation Result

POST https://ai-tokenhub.com/ark?Action=GetModerationResult&Version=2024-01-01

Query the reason an asset/task/request was blocked by content moderation. id/type are passed through to the Volcano side.

Request

Field	Type	Required	Description
id	string	Yes	Resource id (asset id / task id / request id)
type	string	Yes	id type: asset_id / task_id / request_id

Response (Result field)

Field	Type	Description
BlockReasons	array	List of block reasons, see below

BlockReasons element fields: Label (label), SubLabel (sub-label), Detail (detail).

Example

curl -X POST "https://ai-tokenhub.com/ark?Action=GetModerationResult&Version=2024-01-01" \
  -H "Authorization: Bearer pak_XXX:psk_XXX" \
  -H "Content-Type: application/json" \
  -d '{"id":"Asset-2026abc123-def456","type":"asset_id"}'

Response example

{
  "ResponseMetadata": {"RequestId":"...","Action":"GetModerationResult","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "Result": {
    "BlockReasons": [
      {"Label": "Deepfake", "SubLabel": "RealHuman", "Detail": "May involve real human faces"}
    ]
  }
}

---

Error Responses

Except for CreateVisualValidateSession and GetVisualValidateResult, all endpoints return the following on failure:

{
  "ResponseMetadata": {"RequestId":"...","Action":"...","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
  "ResponseError": {"Code": "NotFound", "Message": "resource not found"}
}

Common Code values:

Code	HTTP	Description
InvalidParameter	400	Invalid request parameter
UnsupportedField	400	Field not supported for update (e.g. Name in UpdateAssetGroup)
InvalidAction	400	Unsupported Action
Unauthorized	401	Authentication failed
Forbidden	403	No permission
FeatureNotEnabled	403	Asset library / moderation-result feature not enabled for tenant
NotFound	404	Resource not found or not visible cross-tenant
FailedPrecondition	412	Precondition not met (e.g. uploading to an unready asset group)
Outdated	412	Moderation-result query timed out (older than 14 days)
LimitExceeded	429	Resource count limit reached
ServiceNotConfigured	503	Volcano service not configured
InternalError	500	Internal error