素材库 API 概览

素材库 API 使用火山 ARK Action 协议。12 个操作共用根路径，通过 Action 和固定版本号分发，但在本文档中每个 Action 都有独立接口页、请求结构和响应示例。

POST /?Action={Action}&Version=2024-01-01
Content-Type: application/json

素材库支持两种鉴权方式

AK / SK

签名鉴权

用于素材库、真人认证等 Action API（Action + Version）。

获取路径：用户 API 管理平台 → 访问凭据
请求头：HMAC-SHA256 签名，包含 X-Date 与 X-Content-Sha256
适用：CreateAsset、ListAssets、CreateVisualValidateSession 等

API Key

Bearer 鉴权

用于素材库 Action API，也用于 Seedance 视频生成任务接口。

获取路径：用户 API 管理平台 → 令牌管理
请求头：Authorization: Bearer <API_KEY>
特点：接入简单，素材空间与费用统计按 API Key 对应的用户隔离

两种鉴权任选其一，不要在同一个请求中混用。签名算法、请求头与完整示例请查看素材库认证与签名。

服务地址

服务	Endpoint
用户 API 管理平台（费用、素材、用户隔离）	https://jieyun.cc
界云 Ark 在线调试测试服务	https://arkconsole.jieyun.cc
在线制作工作室	https://arkconsole.jieyun.cc

API 请求使用 https://jieyun.cc。https://arkconsole.jieyun.cc 用于在线调试测试和内容制作，不作为 SDK 或 OpenAPI 请求的 Endpoint。

SDK 与调试工具

资源	地址
Go SDK 配置示例	本文 Go SDK 示例
在线调试与制作	界云 Ark 控制台

Go SDK 支持素材 Action 的 Bearer API Key 与 AK/SK 签名请求。在线文档页的 Action 调试器也提供相同的两套鉴权方式：选择 Bearer 时填写 API Key；选择 AK/SK 时填写 Access Key 和 Secret Key，页面会自动生成 Authorization、X-Date 与 X-Content-Sha256 请求头。

Secret Key 只提交到本站调试代理用于本次签名，不会转发给上游接口，也不会写入浏览器持久化存储或文档服务端存储。生产环境建议优先使用 SDK 或在客户自己的服务端完成签名。

Action 列表

素材组

Action	说明
`CreateAssetGroup`	创建虚拟人像素材组
`ListAssetGroups`	分页查询素材组
`GetAssetGroup`	查询素材组详情
`UpdateAssetGroup`	更新素材组名称或描述
`DeleteAssetGroup`	删除素材组及组内素材

素材

Action	说明
`CreateAsset`	通过 URL 创建图片、视频或音频素材
`ListAssets`	分页查询素材
`GetAsset`	查询素材详情和处理状态
`UpdateAsset`	更新素材名称
`DeleteAsset`	删除素材

真人认证

Action	说明
`CreateVisualValidateSession`	拉起真人认证 H5
`GetVisualValidateResult`	获取认证创建的真人素材组

异步素材流程

CreateAsset 只表示素材进入预处理流程，不表示素材已经可用。创建后应轮询 GetAsset，或使用 ListAssets 按 ID/素材组查询状态：

Processing：正在预处理，暂不可使用。
Active：处理完成，可以使用。
Failed：处理失败，从 Error.Code 和 Error.Message 读取原因。

GetAsset 即使返回 HTTP 200，也可能包含 Status: Failed。业务代码必须同时检查 HTTP 状态与素材状态。响应中的素材 URL 是临时地址，有效期为 12 小时。

公共约束

Version 固定为 2024-01-01。
ProjectName 默认是 default，大小写敏感；非默认项目需传入实际项目名。
创建普通素材组时，GroupType 仅支持 AIGC；真人认证创建的素材组类型为 LivenessFace。
素材类型为 Image、Video、Audio，仅支持公共 URL，不支持 Base64。
分页页码从 1 开始，PageSize 最大为 100。
成功响应包含 ResponseMetadata 和 Result；请求级错误位于 ResponseMetadata.Error。

Go SDK

素材 SDK 提供与 12 个 Action 一一对应的类型化方法。使用 AK/SK 时，服务名为 ark，区域为 cn-beijing：

config := volcengine.NewConfig().
    WithCredentials(credentials.NewStaticCredentials(accessKey, secretKey, "")).
    WithRegion("cn-beijing").
    WithEndpoint("jieyun.cc")

client := ark.New(session.Must(session.NewSession(config)))

result, err := client.GetAsset(&ark.GetAssetInput{
    Id:          volcengine.String("asset-id"),
    ProjectName: volcengine.String("default"),
})

SDK 的 Endpoint 使用 jieyun.cc。在线调试和内容制作请使用界云 Ark 控制台，不要在共享环境或截图中暴露生产凭证。

素材库支持两种鉴权方式

签名鉴权

Bearer 鉴权

目录