火山方舟素材库 API

素材库 OpenAPI 用于管理素材分组与素材资产：把图片、视频、音频提前入库，在生成请求中通过素材 ID 引用。所有接口沿用同一套 Action、Version 与 V4 签名约定，业务数据由平台维护。

所有接口共用同一个入口，通过查询参数 Action 区分具体操作：

POST __DOCS_SITE_ORIGIN__/xmind-cloud-platform/openapi/volcengine?Action=<Action>&Version=2024-01-01

使用场景与流程说明见火山方舟素材库使用指南。

请求约束

仅支持 POST，其他方法返回 InvalidRequest。
Content-Type 必须为 application/json，请求体不能为空。
Version 固定为 2024-01-01，传其他值返回 InvalidVersion。
当前提供素材分组与素材两类接口。
签名区域固定为 cn-beijing，服务固定为 ark，凭证终止段固定为 request。

认证

平台向客户发放 AccessKey 与 SecretKey：前者用于请求中的 Credential，后者仅用于本地计算签名，不能放入请求。如需获取凭证，或遇到与凭证相关的问题，请联系运营人员，详见常见问题。

每次请求必须携带以下请求头：

请求头	说明
`Content-Type`	固定为 `application/json`
`Host`	实际访问的域名和端口，例如 `api.example.com`；包含端口时必须写入签名
`X-Date`	UTC 时间，格式 `yyyyMMdd'T'HHmmss'Z'`，例如 `20261022T131900Z`
`X-Content-Sha256`	原始请求体的 SHA-256 小写十六进制
`Authorization`	V4 HMAC-SHA256 签名

Authorization 格式：

HMAC-SHA256 Credential=<AK>/<yyyyMMdd>/cn-beijing/ark/request, SignedHeaders=content-type;host;x-content-sha256;x-date, Signature=<signature>

<yyyyMMdd> 必须与 X-Date 前 8 位一致。
SignedHeaders 当前固定为 content-type;host;x-content-sha256;x-date。
Signature 为小写十六进制字符串。
请求时间与平台时间偏差不能超过 300 秒。
host 必须与实际访问域名一致。经网关转发时，平台会保留客户端签名的原始 Host。

签名步骤

对原始 JSON 请求体计算 SHA-256，得到小写十六进制 payloadHash。
构造 CanonicalRequest：

POST
/xmind-cloud-platform/openapi/volcengine
<按参数名和参数值编码并排序后的查询字符串>
content-type:application/json
host:<实际 Host>
x-content-sha256:<payloadHash>
x-date:<X-Date>

content-type;host;x-content-sha256;x-date
<payloadHash>

其中 CanonicalHeaders 每一项都以换行符结束；上面的空行是 CanonicalHeaders 与 SignedHeaders 之间的分隔。

对 CanonicalRequest 计算 SHA-256，得到小写十六进制 canonicalHash。
构造 StringToSign：

HMAC-SHA256
<X-Date>
<yyyyMMdd>/cn-beijing/ark/request
<canonicalHash>

按以下顺序派生签名密钥：

kDate    = HMAC-SHA256(SecretKey, yyyyMMdd)
kRegion  = HMAC-SHA256(kDate, cn-beijing)
kService = HMAC-SHA256(kRegion, ark)
kSigning = HMAC-SHA256(kService, request)
signature = HEX(HMAC-SHA256(kSigning, StringToSign))

查询参数、路径和请求体一旦变化，必须重新签名。X-Content-Sha256 必须对实际发送的原始请求体计算，不能对重新格式化后的 JSON 计算。

可以使用页面内的签名工具

各接口页右侧的「请求示例」可以直接填写 Access Key 与 Secret Key，实时生成 X-Date、X-Content-Sha256、Authorization 与完整的 curl 命令，不需要单独计算签名。

通用响应

成功响应：

{
  "ResponseMetadata": {
    "RequestId": "2113258852567580673",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20261026170847-7dnj6"
  }
}

失败响应把错误放在 ResponseMetadata.Error 中，此时不返回 Result：

{
  "ResponseMetadata": {
    "RequestId": "2113250000000000001",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "NotFound.asset_id",
      "Message": "素材不存在"
    }
  }
}

RequestId 是平台为本次调用生成的追踪编号，排查问题时请提供该编号。

本节展示的是响应包络结构；各接口实际返回的字段见对应接口页的「响应」一节。

错误码

Code	含义
`MissingParameter.Action`	缺少 `Action`
`InvalidAction.NotFound`	不支持的 `Action`
`MissingParameter.Version`	缺少 `Version`
`InvalidVersion`	`Version` 不是 `2024-01-01`
`MissingParameter.Authorization`	缺少 `Authorization`
`InvalidAuthorization`	签名头或凭证作用域非法
`SignatureDoesNotMatch`	签名校验失败
`InvalidTimestamp`	`X-Date` 格式错误或超出时间窗口
`XContentSha256Mismatch`	请求体哈希与 `X-Content-Sha256` 不一致
`AccessDenied`	凭证被禁用或无访问权限
`ExpiredToken`	凭证已过期
`InvalidParameter`	参数格式或取值非法
`NotFound.asset_id`	素材不存在
`NotFound.group_id`	分组不存在
`QuotaWriteQPMExceeded`	每分钟写入额度用尽（429）
`AccountFlowLimitExceeded`	接口每秒请求上限触发（429）
`TooManyRequests`	请求过于频繁（429）
`InternalError`	平台内部错误
`InvalidRequest`	请求格式错误

遇到 SignatureDoesNotMatch 时，优先检查 Host、X-Date、请求体是否被重新格式化，以及查询参数是否被改写。

限流

错误码	触发原因	建议
`QuotaWriteQPMExceeded`	每分钟写入次数用尽	等到下一分钟重试
`AccountFlowLimitExceeded`	每秒请求上限触发	约 1 秒后重试

收到 429 一律按指数退避重试，不要当成素材不存在而删除本地记录。
批量删除整批被限流时返回 429，不是 NotFound.asset_id。

分页

列表接口支持页码分页与游标分页两种模式，同一次请求不能混用。

页码分页

{
  "PageNumber": 1,
  "PageSize": 20
}

分页参数不传时默认第 1 页、每页 20 条。
PageSize 取 1-100。
ListAssetGroups 的 PageSize * PageNumber 上限 10000；ListAssets 上限 20000。
超过页码窗口时须改用 NextToken 进行深翻页。
返回 TotalCount、PageNumber、PageSize。

游标分页

{
  "MaxResults": 20,
  "NextToken": "可选，首次请求不传"
}

MaxResults 取 1-100。
有下一页时返回 NextToken，没有下一页时不返回该字段。
NextToken 不能跨不同的 MaxResults 复用。

接口索引

所有接口共用路径 /xmind-cloud-platform/openapi/volcengine，下表只列 Action 与用途。

素材分组

接口	Action	说明
查询分组列表	`ListAssetGroups`	按分组类型、分组 ID、名称查询分组
查询分组详情	`GetAssetGroup`	按分组 ID 查询单个分组
创建分组	`CreateAssetGroup`	创建分组，返回分组 ID
重命名分组	`UpdateAssetGroup`	修改分组名称
删除分组	`DeleteAssetGroup`	删除分组及组内素材

素材

接口	Action	说明
查询素材列表	`ListAssets`	按分组、名称、状态、一次性标记查询素材
查询素材详情	`GetAsset`	按素材 ID 查询详情与入库状态
上传素材	`CreateAsset`	上传素材，同步返回素材 ID
更新素材	`UpdateAsset`	修改素材名称
删除素材	`DeleteAsset`	删除素材，支持单个或批量

一次性素材

用于「只被模型调用一次、用完即删」的场景，减少长期存储占用。

用法：CreateAsset 时传 "OneTime": true，不传或传 false 为永久素材。一次性标记创建后不可修改。
行为：素材被模型调用并完成后，平台自动删除该素材。删除由模型调用结算驱动，不是调用后立即删除；删除前仍可正常查询和使用。重复的结算事件不会导致报错。
注意：删除时机取决于模型调用结算，若需要严格的生命周期保证，请在业务侧自行管理。一次性素材在删除前同样占用存储额度，不适合需要长期回查的素材。

ListAssets 支持 Filter.OneTime 筛选，GetAsset 与 ListAssets 均返回 OneTime 字段，详见上传素材与查询素材列表。

接入建议

CreateAsset 返回后即可用 Id；素材入库是异步的，状态见 Status。
预览 URL 只用于短期展示，不要写入长期数据库。
收到 429 按限流退避重试，不要当作素材不存在。
一次性素材的删除由模型调用结算驱动，需要严格生命周期控制请在业务侧自行管理。
遇到 SignatureDoesNotMatch 时，优先检查 Host、X-Date、请求体是否被重新格式化、查询参数是否被改写。

请求约束​

认证​

签名步骤​

通用响应​

错误码​

限流​

分页​

页码分页​

游标分页​

接口索引​

素材分组​

素材​

一次性素材​

接入建议​

相关文档​