TokenHub-火山ark兼容接口 调用说明
tokenhub 提供与火山 ark 接口格式兼容的 API 面，便于用户在不改动原有火山调用方式的前提下，快速适配到 tokenhub。所有接口共用一个入口，通过 query 参数 Action 区分操作；返回值统一为火山风格（Result 中的 id 均为火山 id）。
快速开始
获取 AK/SK
登录 ai-tokenhub 控制台，进入令牌管理页面，选择 AK/SK，点击开具。
- 访问密钥 ID（AK）：以
pak开头 - 秘密钥匙（SK）：以
psk开头 - 重要：SK 仅在生成时显示一次，请妥善保存。
通用说明
- Base URL：
https://ai-tokenhub.com - 入口：
POST /ark?Action=<操作名>&Version=2024-01-01 - 鉴权：所有接口使用 tokenhub 个人访问凭证（AK/SK），通过
Authorization头传入：凭证所属租户即为调用租户，接口内不需要传租户 ID。Authorization: Bearer pak_XXX:psk_XXX - 请求体：
application/json，字段为火山风格 PascalCase（GetModerationResult例外，用id/type）。 ProjectName字段：火山接口普遍带该字段，本兼容面忽略其传入值，统一使用平台配置值（default），可传可不传。- 通用响应信封（除
CreateVisualValidateSession与GetVisualValidateResult外）：- 成功：
{"ResponseMetadata": {RequestId, Action, Version, Service, Region}, "Result": {...}} - 失败：
{"ResponseMetadata": {...}, "ResponseError": {"Code": "...", "Message": "..."}} ResponseMetadata字段：RequestId（请求标识）、Action（操作名）、Version（2024-01-01）、Service（ark）、Region（cn-beijing）。
- 成功：
- 状态枚举（素材
Status）：Active（就绪）、Processing（处理中）、Failed（失败）。 - id 说明：响应中的
Id/GroupId均为火山 id（素材组group-...、素材Asset-...），可直接用于后续接口入参，形成闭环。
1. 获取真人认证 H5 链接
POST https://ai-tokenhub.com/ark?Action=CreateVisualValidateSession&Version=2024-01-01
获取真人认证 H5 链接。该接口成功响应不包 ResponseMetadata/Result 信封，直接返回下述字段。
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| CallbackURL | string | 是 | 认证结束后跳转的可访问 URL |
| ProjectName | string | 否 | 资源所属项目名（忽略，用配置默认值） |
Response（直接返回，无信封）
| 字段 | 类型 | 说明 |
|---|---|---|
| BytedToken | string | 认证 token |
| H5Link | string | H5 认证链接 |
| CallbackURL | string | 回调地址 |
请求示例
bash
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"}'响应示例
json
{
"BytedToken": "bt_abc123def456",
"H5Link": "https://ark.volcengine.com/region:c",
"CallbackURL": "https://www.example.com/callback"
}2. 获取真人认证结果
POST https://ai-tokenhub.com/ark?Action=GetVisualValidateResult&Version=2024-01-01
用 CreateVisualValidateSession 返回的 BytedToken 查询真人认证结果，返回火山素材组 id。该接口成功响应不包 ResponseMetadata/Result 信封，直接返回下述字段（与火山该接口一致，同 CreateVisualValidateSession）。当真人认证尚未完成时 GroupId 为空串，调用方可继续轮询。
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| BytedToken | string | 是 | CreateVisualValidateSession 返回的认证 token |
Response（直接返回，无信封）
| 字段 | 类型 | 说明 |
|---|---|---|
| GroupId | string | 火山素材组 id（group-...）；真人认证未完成时为空串 |
请求示例
bash
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"}'响应示例
json
{
"GroupId": "group-20260331145705-xxxxx"
}3. 创建虚拟素材组
POST https://ai-tokenhub.com/ark?Action=CreateAssetGroup&Version=2024-01-01
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Name | string | 是 | 素材组名称 |
| Description | string | 否 | 素材组描述 |
| GroupType | string | 是 | 素材组类型，当前仅支持 AIGC |
| ProjectName | string | 否 | 忽略，用配置默认值 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| Id | string | 素材组 id（火山格式 group-...） |
请求示例
bash
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"}'响应示例
json
{
"ResponseMetadata": {
"RequestId": "20260709123000000000000000000000",
"Action": "CreateAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Id": "group-2026abc123-def456"
}
}4. 列出素材组
POST https://ai-tokenhub.com/ark?Action=ListAssetGroups&Version=2024-01-01
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Filter.Name | string | 否 | 名称模糊匹配 |
| Filter.GroupType | string | 否 | 素材组类型（AIGC） |
| PageNumber | int | 是 | 页码，从 1 开始 |
| PageSize | int | 是 | 每页数量 |
| SortBy | string | 否 | 忽略（不支持排序） |
| SortOrder | string | 否 | 忽略 |
| ProjectName | string | 否 | 忽略 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| TotalCount | int | 总数 |
| Items | array | 素材组列表，见下 |
| PageNumber | int | 当前页码 |
| PageSize | int | 每页数量 |
Items 元素字段：Id（火山组 id）、Name、Description、GroupType、CreateTime、UpdateTime（RFC3339）。
请求示例
bash
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}'响应示例
json
{
"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. 获取素材组详情
POST https://ai-tokenhub.com/ark?Action=GetAssetGroup&Version=2024-01-01
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材组 id（火山格式 group-...） |
| ProjectName | string | 否 | 忽略 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| Id | string | 火山组 id |
| Name | string | 名称 |
| Description | string | 描述 |
| GroupType | string | 类型 |
| CreateTime | string | 创建时间（RFC3339） |
| UpdateTime | string | 更新时间（RFC3339） |
请求示例
bash
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"}'响应示例
json
{
"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. 编辑素材组
POST https://ai-tokenhub.com/ark?Action=UpdateAssetGroup&Version=2024-01-01
当前仅支持修改 Description。若传入与现值不同的 Name，返回 400 UnsupportedField。
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材组 id |
| Name | string | 否 | 不支持修改（传不同值会报 UnsupportedField） |
| Description | string | 否 | 新描述 |
| ProjectName | string | 否 | 忽略 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| Id | string | 火山组 id |
请求示例
bash
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"}'响应示例
json
{
"ResponseMetadata": {"RequestId":"...","Action":"UpdateAssetGroup","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
"Result": {
"Id": "group-2026abc123-def456"
}
}7. 删除素材组
POST https://ai-tokenhub.com/ark?Action=DeleteAssetGroup&Version=2024-01-01
同步删除火山侧资源。
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材组 id |
| ProjectName | string | 否 | 忽略 |
Response（Result 为空对象 {}）
请求示例
bash
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"}'响应示例
json
{
"ResponseMetadata": {"RequestId":"...","Action":"DeleteAssetGroup","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
"Result": {}
}8. 列出素材
POST https://ai-tokenhub.com/ark?Action=ListAssets&Version=2024-01-01
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Filter.GroupIds | []string | 否 | 素材组 id 列表，支持跨组查询 |
| Filter.GroupType | string | 否 | 素材组类型 |
| Filter.Statuses | []string | 否 | 状态筛选（Active/Processing/Failed） |
| Filter.Name | string | 否 | 名称模糊匹配 |
| PageNumber | int | 是 | 页码 |
| PageSize | int | 是 | 每页数量 |
| SortBy / SortOrder | string | 否 | 忽略 |
| ProjectName | string | 否 | 忽略 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| TotalCount | int | 总数 |
| Items | array | 素材列表，见下 |
| PageNumber | int | 当前页码 |
| PageSize | int | 每页数量 |
Items 元素字段：Id（火山素材 id）、Name、URL（素材可访问地址）、GroupId（火山组 id）、AssetType（Image/Video/Audio）、Status（Active/Processing/Failed）、Error.Code/Error.Message（失败时填充，成功为空）、ProjectName、CreateTime、UpdateTime。
请求示例
bash
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}'响应示例
json
{
"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. 上传素材
POST https://ai-tokenhub.com/ark?Action=CreateAsset&Version=2024-01-01
同步上传：响应即返回火山素材 id（无需轮询回填）。URL 需为公网可访问地址，否则火山侧会注册失败。
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| GroupId | string | 是 | 素材组 id |
| URL | string | 是 | 素材的公共可访问地址 |
| Name | string | 是 | 素材名称 |
| AssetType | string | 是 | 素材类型（Image/Video/Audio） |
| ProjectName | string | 否 | 忽略 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| Id | string | 火山素材 id（Asset-...） |
请求示例
bash
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"}'响应示例
json
{
"ResponseMetadata": {"RequestId":"...","Action":"CreateAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
"Result": {
"Id": "Asset-2026abc123-def456"
}
}10. 获取素材详情
POST https://ai-tokenhub.com/ark?Action=GetAsset&Version=2024-01-01
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材 id（火山格式 Asset-...） |
| ProjectName | string | 否 | 忽略 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| Id | string | 火山素材 id |
| Name | string | 名称 |
| URL | string | 素材可访问地址 |
| GroupId | string | 所属火山组 id |
| AssetType | string | 类型 |
| Status | string | Active/Processing/Failed |
| Error.Code | string | 失败错误码（成功为空） |
| Error.Message | string | 失败错误信息（成功为空） |
| ProjectName | string | 项目名 |
| CreateTime | string | 创建时间（RFC3339） |
| UpdateTime | string | 更新时间（RFC3339） |
请求示例
bash
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"}'响应示例
json
{
"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. 编辑素材
POST https://ai-tokenhub.com/ark?Action=UpdateAsset&Version=2024-01-01
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材 id |
| Name | string | 否 | 新名称 |
| ProjectName | string | 否 | 忽略 |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| Id | string | 火山素材 id |
请求示例
bash
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"}'响应示例
json
{
"ResponseMetadata": {"RequestId":"...","Action":"UpdateAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
"Result": {
"Id": "Asset-2026abc123-def456"
}
}12. 删除素材
POST https://ai-tokenhub.com/ark?Action=DeleteAsset&Version=2024-01-01
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| Id | string | 是 | 素材 id |
| ProjectName | string | 否 | 忽略 |
Response（Result 为空对象 {}）
请求示例
bash
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"}'响应示例
json
{
"ResponseMetadata": {"RequestId":"...","Action":"DeleteAsset","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
"Result": {}
}13. 获取拦截原因
POST https://ai-tokenhub.com/ark?Action=GetModerationResult&Version=2024-01-01
查询素材/任务/请求被内容审核拦截的原因。id/type 透传至火山侧。
Request
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
| id | string | 是 | 资源 id（素材 id / 任务 id / request id） |
| type | string | 是 | id 类型：asset_id / task_id / request_id |
Response（Result 字段）
| 字段 | 类型 | 说明 |
|---|---|---|
| BlockReasons | array | 拦截原因列表，见下 |
BlockReasons 元素字段：Label（标签）、SubLabel（子标签）、Detail（详情）。
请求示例
bash
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"}'响应示例
json
{
"ResponseMetadata": {"RequestId":"...","Action":"GetModerationResult","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
"Result": {
"BlockReasons": [
{"Label": "Deepfake", "SubLabel": "RealHuman", "Detail": "可能涉及真人人脸"}
]
}
}错误响应
除 CreateVisualValidateSession 与 GetVisualValidateResult 外，所有接口失败时返回：
json
{
"ResponseMetadata": {"RequestId":"...","Action":"...","Version":"2024-01-01","Service":"ark","Region":"cn-beijing"},
"ResponseError": {"Code": "NotFound", "Message": "resource not found"}
}常见 Code：
| Code | HTTP | 说明 |
|---|---|---|
| InvalidParameter | 400 | 请求参数非法 |
| UnsupportedField | 400 | 不支持修改的字段（如 UpdateAssetGroup 的 Name） |
| InvalidAction | 400 | 不支持的 Action |
| Unauthorized | 401 | 鉴权失败 |
| Forbidden | 403 | 无权限 |
| FeatureNotEnabled | 403 | 租户未开启素材库/拦截原因功能 |
| NotFound | 404 | 资源不存在或跨租户不可见 |
| FailedPrecondition | 412 | 前置条件不满足（如素材组未就绪不可上传） |
| Outdated | 412 | 拦截原因查询超时（超过 14 天） |
| LimitExceeded | 429 | 资源数量达上限 |
| ServiceNotConfigured | 503 | 火山服务未配置 |
| InternalError | 500 | 内部错误 |