资源库 API 接入文档（火山官方格式）

本文档描述 api.aiide.com 提供的资源库代理 API，接口采用火山引擎 Ark Universal API 的请求和响应风格，面向下游 SDK、Agent 以及脚本客户端。

功能说明

✅ 支持素材组（AssetGroup）和素材文件（Asset）管理

✅ 支持 AK/SK HMAC-SHA256 签名鉴权和 API Key Bearer 鉴权

❌ 当前版本不提供真人库活体校验接口（CreateVisualValidateSession、GetVisualValidateResult）

1. 接口地址

Base URL:

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

请求方式: POST

URL 格式:

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

固定参数

参数	固定值	必填	说明
`Action`	见操作列表	✅	URL 查询参数，指定操作类型
`Version`	`2024-01-01`	✅	API 版本号（建议所有请求传入）
`Content-Type`	`application/json`	✅	HTTP 请求头

响应元数据固定值:

Service: ark

Region: cn-beijing

⚠️ 注意: 请勿使用其他版本号，服务端按固定值生成响应元数据。

2. 协议说明

素材库 API 使用 火山引擎 ARK Action 协议。所有操作共用根路径 /v1/ark/asset/，通过 Action 查询参数和固定版本号 Version=2024-01-01 进行分发。

标准请求格式:

本文档中每个 Action 都有独立的接口说明、请求结构和响应示例。

3. 鉴权

素材库支持 两种鉴权方式，二选一使用，不要在同一个请求中混用。

3.1 方式一：AK/SK 签名鉴权（使用火山官方 SDK）

适用场景:

素材库 Action API（如 CreateAsset、ListAssets 等）

获取路径:

用户 API 管理平台 → 访问凭据

请求头要求:

说明:

使用 HMAC-SHA256 算法对请求进行签名

需要包含 X-Date 和 X-Content-Sha256 请求头

完全兼容火山引擎官方 SDK（volcengine-go-sdk）的签名方式

素材访问按访问凭据对应的用户进行隔离

签名算法详情请参考火山引擎官方文档

3.2 方式二：API Key Bearer 鉴权

适用场景:

素材库 Action API

Seedance 视频生成任务接口

获取路径:

用户 API 管理平台 → 令牌管理

请求头格式:

特点:

✅ 接入简单，无需复杂的签名计算

✅ 素材空间与费用统计按 API Key 对应的用户隔离

✅ 支持额度、分组和 IP 限制等平台统一规则

示例:

3.3 使用火山引擎官方 SDK 接入

火山官方 SDK 默认指向 open.volcengineapi.com。接入本服务只需修改 Endpoint 并选择一种鉴权方式。

使用 AK/SK 凭据（推荐）

⚠️ Endpoint 末尾不要带 /：官方 universal SDK 会自动在路径后补一个 /，配置为 .../asset 即可（实际请求为 .../asset/）。若写成 .../asset/ 会产生双斜杠导致 404。

其它语言的官方 SDK 同理：将 endpoint / base_url 指向本服务的 /v1/ark/asset 路径，并根据所选鉴权方式配置 AK/SK 或通过 SDK 的拦截器机制添加 Authorization: Bearer <token> 请求头。

4. 数据隔离和资源模型

4.1 资源对象

资源库包含两类对象：

对象类型	说明	关系
AssetGroup	素材组	用于组织同一类素材
Asset	素材文件	必须归属于一个素材组

4.2 数据隔离规则

隔离维度:

API Key 对应的用户账号

访问规则:

✅ 使用同一个 API Key 可以访问该 Key 关联用户的所有素材组和素材

✅ 使用 AK/SK 签名时，按访问凭据关联的用户进行隔离

❌ 不同用户之间不能互相访问资源

4.3 素材组配置

通过 CreateAssetGroup 创建的素材组统一使用以下固定配置：

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

📌 说明:
GroupType 和 ProjectName 不需要在创建请求中传入，服务端自动设置
当前版本不支持通过 CreateVisualValidateSession / GetVisualValidateResult 创建 LivenessFace 真人素材组

4.4 素材状态

上传素材后，服务端根据素材供应商映射计算对当前用户可见的状态：

状态	说明	可用性
`Processing`	素材仍在处理中	❌ 暂不可使用
`Active`	素材已处理完成	✅ 可以在视频生成请求中使用
`Failed`	素材处理失败	❌ 响应中的 `Error` 字段可能包含失败原因

4.5 素材引用格式

在视频生成请求中使用素材的标准引用格式：

asset://<asset_id>

示例:

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

⚠️ 注意: 具体模型是否支持某类素材，由已配置的素材供应商和模型能力决定。

5. 请求和响应格式

5.1 成功响应

HTTP 状态码: 200 OK

响应体结构:

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

字段说明:

字段	类型	说明
`ResponseMetadata`	Object	响应元数据
`ResponseMetadata.RequestId`	String	请求唯一标识符
`ResponseMetadata.Action`	String	操作名称
`ResponseMetadata.Version`	String	API 版本号
`ResponseMetadata.Service`	String	服务名称（固定为 `ark`）
`ResponseMetadata.Region`	String	区域（固定为 `cn-beijing`）
`Result`	Object	操作结果数据

5.2 错误响应

响应体结构:

{
  "ResponseMetadata": {
    "RequestId": "request-id",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "ResourceNotFound",
      "Message": "素材不存在"
    }
  },
  "Result": null
}

5.3 错误码列表

HTTP 状态码	错误码	说明	常见原因
`400`	`InvalidParameter`	请求参数无效	请求体缺少必填字段或字段值不合法
`400`	`UnsupportedAction`	不支持的操作	`Action` 参数值不在支持列表中
`401`	`Unauthorized`	鉴权失败	Bearer Token 无效或聚合用户请求头缺失/无效
`403`	`PermissionDenied`	权限不足	资源属于其他用户，或无权访问
`404`	`ResourceNotFound`	资源不存在	请求的素材组或素材不存在
`500`	`InternalError`	内部错误	服务端或素材处理服务异常

6. 支持的操作

当前支持以下 Action 操作：

素材组操作

Action	说明
`CreateAssetGroup`	创建素材组
`GetAssetGroup`	获取素材组详情
`ListAssetGroups`	列出素材组
`UpdateAssetGroup`	更新素材组
`DeleteAssetGroup`	删除素材组

素材操作

Action	说明
`CreateAsset`	创建/上传素材
`GetAsset`	获取素材详情
`ListAssets`	列出素材
`UpdateAsset`	更新素材
`DeleteAsset`	删除素材

📌 说明: 具体请求参数和响应字段请参考火山引擎 Ark Universal API 文档或向平台方索取详细接口规范。

7. 素材组接口详细说明

7.1 CreateAssetGroup

创建一个新的素材组。

请求示例:

请求体字段:

字段	类型	必填	说明
`Name`	string	✅	素材组名称，1-64 个字符
`Description`	string	❌	素材组描述，最多 300 个字符

成功响应:

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

7.2 ListAssetGroups

分页列出当前用户的素材组。

请求示例:

请求体字段:

字段	类型	必填	默认值	说明
`Filter.GroupIds`	string[]	❌	-	按素材组 ID 列表过滤
`Filter.Name`	string	❌	-	按素材组名称过滤
`Filter.GroupType`	string	❌	-	按素材组类型过滤（如 `AIGC`）
`PageNumber`	integer	❌	1	页码，从 1 开始
`PageSize`	integer	❌	10	每页数量，最大 100
`SortBy`	string	❌	`CreateTime`	排序字段：`CreateTime` 或 `UpdateTime`
`SortOrder`	string	❌	`Desc`	排序方向：`Desc` 或 `Asc`

成功响应:

{
  "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": "我的素材组",
        "Description": "用于存放虚拟人像素材",
        "GroupType": "AIGC",
        "ProjectName": "default",
        "CreateTime": "2026-08-21T12:00:00Z",
        "UpdateTime": "2026-08-21T12:00:00Z"
      }
    ],
    "PageNumber": 1,
    "PageSize": 20
  }
}

7.3 GetAssetGroup

获取素材组详情。

请求示例:

请求体字段:

字段	类型	必填	说明
`Id`	string	✅	素材组 ID
`ProjectName`	string	❌	项目名称（需与素材组项目一致）

成功响应:

{
  "ResponseMetadata": {
    "RequestId": "req-20260821-003",
    "Action": "GetAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260821120000-abcde",
    "Name": "我的素材组",
    "Description": "用于存放虚拟人像素材",
    "GroupType": "AIGC",
    "ProjectName": "default",
    "CreateTime": "2026-08-21T12:00:00Z",
    "UpdateTime": "2026-08-21T12:00:00Z"
  }
}

7.4 UpdateAssetGroup

更新素材组名称或描述。

请求示例:

请求体字段:

字段	类型	必填	说明
`Id`	string	✅	素材组 ID
`Name`	string	❌	新的素材组名称，1-64 个字符
`Description`	string	❌	新的素材组描述，最多 300 个字符

成功响应:

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

7.5 DeleteAssetGroup

删除素材组。

请求示例:

请求体字段:

字段	类型	必填	说明
`Id`	string	✅	素材组 ID
`ProjectName`	string	❌	项目名称（需与素材组项目一致）

成功响应:

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

8. 素材接口详细说明

8.1 CreateAsset

将公网 URL 登记为素材，返回素材 ID 和初始状态。

请求示例:

请求体字段:

字段	类型	必填	说明
`Name`	string	✅	素材名称，1-64 个字符
`URL`	string	✅	素材公网 URL
`AssetType`	string	✅	素材类型，当前仅支持 `Image`
`GroupId`	string	✅	所属素材组 ID

成功响应:

{
  "ResponseMetadata": {
    "RequestId": "req-20260821-006",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260821120100-fghij"
  }
}

8.2 GetAsset

获取素材详情和当前状态。

请求示例:

请求体字段:

字段	类型	必填	说明
`Id`	string	✅	素材 ID

成功响应:

{
  "ResponseMetadata": {
    "RequestId": "req-20260821-007",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260821120100-fghij",
    "Name": "host-a-front",
    "URL": "https://cdn.example.com/portrait.jpg",
    "AssetType": "Image",
    "GroupId": "group-20260821120000-abcde",
    "Status": "Active",
    "Moderation": {
      "Strategy": "Default"
    },
    "CreateTime": "2026-08-21T12:01:00Z",
    "UpdateTime": "2026-08-21T12:01:05Z",
    "ProjectName": "default"
  }
}

8.3 ListAssets

分页列出当前用户可见的素材。

请求示例:

请求体字段:

字段	类型	必填	说明
`Filter.GroupIds`	string[]	❌	按素材组 ID 列表过滤
`Filter.GroupType`	string	❌	按素材组类型过滤，当前可使用 `AIGC`
`Filter.Name`	string	❌	按素材名称过滤
`PageNumber`	integer	❌	页码，从 1 开始，默认 1
`PageSize`	integer	❌	每页数量，默认 10，最大 100
`SortBy`	string	❌	排序字段：`CreateTime`、`UpdateTime` 或 `GroupId`，默认 `CreateTime`
`SortOrder`	string	❌	排序方向：`Desc` 或 `Asc`，默认 `Desc`

成功响应:

{
  "ResponseMetadata": {
    "RequestId": "req-20260821-008",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Items": [
      {
        "Id": "asset-20260821120100-fghij",
        "Name": "host-a-front",
        "URL": "https://cdn.example.com/portrait.jpg",
        "GroupId": "group-20260821120000-abcde",
        "AssetType": "Image",
        "Status": "Active",
        "Moderation": {
          "Strategy": "Default"
        },
        "CreateTime": "2026-08-21T12:01:00Z",
        "UpdateTime": "2026-08-21T12:01:05Z",
        "ProjectName": "default"
      }
    ],
    "TotalCount": 1,
    "PageNumber": 1,
    "PageSize": 20
  }
}

8.4 UpdateAsset

更新素材名称。

请求示例:

请求体字段:

字段	类型	必填	说明
`Id`	string	✅	素材 ID
`Name`	string	✅	新的素材名称，1-64 个字符

成功响应:

{
  "ResponseMetadata": {
    "RequestId": "req-20260821-009",
    "Action": "UpdateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260821120100-fghij"
  }
}

8.5 DeleteAsset

删除素材。

请求示例:

请求体字段:

字段	类型	必填	说明
`Id`	string	✅	素材 ID

成功响应:

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

9. 推荐接入流程

虚拟人像素材的典型流程如下：

使用 CreateAssetGroup 创建一个 AIGC 素材组

使用 CreateAsset 将公网 URL 登记到该素材组

记录返回的 asset_id

使用 GetAsset 轮询素材状态

状态为 Active 后，在视频生成请求中使用 asset://<asset_id>

不再使用时调用 DeleteAsset，必要时再调用 DeleteAssetGroup

简单轮询示例:

10. 与火山引擎官方 API 的差异

本接口复用了火山引擎 Universal API 的 Action、字段命名和响应信封，但它是本站的资源库代理，不是火山引擎官方资源库。接入时请注意：

✅ 当前支持 API Key Bearer 鉴权

✅ 当前支持 AK/SK HMAC-SHA256 签名鉴权

✅ 当前所有接口只支持 POST 方法

❌ CreateVisualValidateSession 和 GetVisualValidateResult 当前不支持

📌 当前创建的素材组固定为 GroupType=AIGC、ProjectName=default

📌 GetAssetGroup、UpdateAssetGroup、DeleteAssetGroup 使用请求体字段 Id

📌 CreateAssetGroup 和 CreateAsset 的成功结果字段使用 Result.Id

📌 CreateAsset 只接受公网 URL，不接受 Base64 或 multipart 文件上传

📌 返回的 URL 是本站保存的原始素材 URL，不应当当作短期预签名地址处理

资源库 API 接入文档（火山官方格式）

功能说明#

目录#

1. 接口地址#

固定参数#

2. 协议说明#

3. 鉴权#

3.1 方式一：AK/SK 签名鉴权（使用火山官方 SDK）#

3.2 方式二：API Key Bearer 鉴权#

3.3 使用火山引擎官方 SDK 接入#

使用 AK/SK 凭据（推荐）#

4. 数据隔离和资源模型#

4.1 资源对象#

4.2 数据隔离规则#

4.3 素材组配置#

4.4 素材状态#

4.5 素材引用格式#

5. 请求和响应格式#

5.1 成功响应#

5.2 错误响应#

5.3 错误码列表#

6. 支持的操作#

素材组操作#

素材操作#

7. 素材组接口详细说明#

7.1 CreateAssetGroup#

7.2 ListAssetGroups#

7.3 GetAssetGroup#

7.4 UpdateAssetGroup#

7.5 DeleteAssetGroup#

8. 素材接口详细说明#

8.1 CreateAsset#

8.2 GetAsset#

8.3 ListAssets#

8.4 UpdateAsset#

8.5 DeleteAsset#

9. 推荐接入流程#

10. 与火山引擎官方 API 的差异#

功能说明

目录

1. 接口地址

固定参数

2. 协议说明

3. 鉴权

3.1 方式一：AK/SK 签名鉴权（使用火山官方 SDK）

3.2 方式二：API Key Bearer 鉴权

3.3 使用火山引擎官方 SDK 接入

使用 AK/SK 凭据（推荐）

4. 数据隔离和资源模型

4.1 资源对象

4.2 数据隔离规则

4.3 素材组配置

4.4 素材状态

4.5 素材引用格式

5. 请求和响应格式

5.1 成功响应

5.2 错误响应

5.3 错误码列表

6. 支持的操作

素材组操作

素材操作

7. 素材组接口详细说明

7.1 CreateAssetGroup

7.2 ListAssetGroups

7.3 GetAssetGroup

7.4 UpdateAssetGroup

7.5 DeleteAssetGroup

8. 素材接口详细说明

8.1 CreateAsset

8.2 GetAsset

8.3 ListAssets

8.4 UpdateAsset

8.5 DeleteAsset

9. 推荐接入流程

10. 与火山引擎官方 API 的差异