素材库 API 概览

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

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

服务地址

服务	Endpoint
界云 Ark 素材服务	`https://jieyun.cc`
RealmRouter 兼容服务	`https://realmrouter.cn`

两套地址使用相同的 Action、Version、请求体与签名规则。请使用账号实际开通的 Endpoint，不要在同一次资源流程中混用服务地址。

SDK 与调试工具

资源	地址
Go SDK 源码与下载	jieyun-go-sdk
在线素材调试器	ARK Debugger

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 和在线验证工具也可直接连接兼容火山 ARK Action 协议的 RealmRouter Endpoint。调试时可使用素材验证工具，但不要在共享环境中填写生产凭证。

目录