火山方舟官方素材库兼容接口使用说明

适用范围

本说明面向需要按火山方舟素材库 Action 协议调用本系统的终端用户，说明素材库的鉴权格式、请求字段和响应结构。

系统签发的 AccessKey/SecretKey 仅能调用本说明列出的素材库接口，不能用于后台登录、模型调用或访问火山云账号。请勿将火山云账号 AK/SK 填入本系统，也不要把系统 AK/SK 用于火山云官方域名。

获取系统 AK/SK

登录管理台，进入“素材库 > API 凭证”。

创建 API 凭证；可选填 IP 白名单。

在创建或重置完成时保存 AccessKey 与 SecretKey。SecretKey 只展示一次，关闭后无法再次查看明文。

凭证被停用、删除，所属用户被停用，或请求 IP 不在白名单时，后续调用会被拒绝。

请求入口

POST https://<系统域名>/volcengine/ark?Action=<Action>&Version=2024-01-01

根路径 / 是控制台前端页面，不能作为 SDK 或 API 调用入口。兼容入口固定为 /volcengine/ark。

HMAC-SHA256 V4 鉴权

每个请求必须使用原始 JSON body 生成摘要和签名。建议固定签名头为：

content-type;host;x-content-sha256;x-date

请求头示例：

签名计算步骤：

对原始请求体计算 SHA-256，填入 X-Content-Sha256。

将查询参数按键和值排序；至少包含 Action 和 Version=2024-01-01。

构造 canonical request：HTTP 方法、/volcengine/ark、规范化查询串、规范化已签名头、已签名头列表、body 摘要。

对 canonical request 计算 SHA-256，构造 string-to-sign：HMAC-SHA256、X-Date、YYYYMMDD/cn-beijing/ark/request、canonical request 摘要。

用 SecretKey 依次派生日期、区域 cn-beijing、服务 ark、request 的 HMAC key，计算最终 Signature。

填入 Authorization 头。签名时和发送时的 body、路径、查询参数、已签名头必须完全一致。

服务端允许 15 分钟时钟偏差。签名或 body 摘要不匹配、必要签名头缺失、时间超窗、AccessKey 不存在时返回 HTTP 401；凭证/用户被停用或 IP 未授权时返回 HTTP 403。

Action 清单

Action	用途	关键请求字段
`CreateVisualValidateSession`	创建真人扫码授权会话	`CallbackURL`，可选 `Name`、`Description`、`ProjectName`
`GetVisualValidateResult`	查询授权并取得 `GroupId`	`BytedToken`，可选 `ProjectName`
`CreateAssetGroup`	创建普通素材资产组合	`Name`，可选 `Description`、`GroupType=AIGC`、`ProjectName`
`CreateAsset`	向素材目录上传一个素材	`GroupId`、`URL`、`AssetType`，可选 `Name`、`ProjectName`
`ListAssetGroups`	查询素材目录	`Filter`、`PageNumber`、`PageSize`
`ListAssets`	查询指定目录的素材	`Filter.GroupIds`、`PageNumber`、`PageSize`
`GetAsset` / `GetAssetGroup`	查询单个素材或目录	`Id`，可选 `ProjectName`
`UpdateAsset` / `UpdateAssetGroup`	更新素材名称或目录名称/描述	`Id`、`Name`，目录可传 `Description`
`DeleteAsset` / `DeleteAssetGroup`	删除素材或目录	`Id`，可选 `ProjectName`

所有成功响应都使用：

{
  "ResponseMetadata": {
    "RequestId": "req_xxx",
    "Action": "ListAssetGroups",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {}
}

失败响应在 ResponseMetadata.Error 中返回稳定错误码和说明。资源不存在或不属于当前 AccessKey 所属用户时均返回 HTTP 404，避免泄漏其他用户资源。

真人扫码授权

创建会话：

{
  "CallbackURL": "https://client.example.com/asset-callback",
  "Name": "本人授权素材",
  "Description": "用于短视频生成"
}

返回的 BytedToken 是本次认证会话标识。终端用户完成 H5 页面或二维码扫码后，系统会以 303 跳转到 CallbackURL，并追加：

?bytedToken=<系统公开token>&resultCode=10000&groupId=<GroupId>

resultCode=10000 表示认证页面成功；之后仍应调用 GetVisualValidateResult 确认已取得 GroupId。

上传、查询和生成

创建普通素材组

非人像图片、视频和音频素材应先创建 AIGC 类型的 Asset Group。创建成功后使用返回的 Result.Id 作为 CreateAsset 的 GroupId：

{
  "Name": "商品素材",
  "Description": "商品图片、视频和音频",
  "GroupType": "AIGC",
  "ProjectName": "default"
}

Name 为必填，最长 64 字符；Description 最长 300 字符；当前仅支持 AIGC。若未填写 ProjectName，系统按 default 处理。

创建素材示例：

{
  "GroupId": "group-20260827120000-example",
  "URL": "https://example.com/material.jpg",
  "AssetType": "Image",
  "Name": "正面特写"
}

返回的 Id 是后续 GetAsset、UpdateAsset、DeleteAsset 使用的素材 ID。状态映射如下：

兼容状态	含义	是否可引用
`Processing`	处理中/审核中	否
`Active`	已可用	是
`Failed`	处理失败、拒绝或需重新认证/上传	否

素材仍处于 Processing 时，可轮询 GetAsset 查询最新状态；ListAssets 和 ListAssetGroups 用于分页查询当前素材和素材组。

当素材状态为 Active 后，在 Seedance 请求的 image_url.url、video_url.url 或 audio_url.url 中使用：

asset://<Asset Id>

Prompt 使用“图片1”“视频1”等顺序指代输入素材，不要在 Prompt 文本中直接写素材 ID。

常见错误

HTTP 状态	错误码	场景
400	`InvalidAction` / `InvalidVersion` / `InvalidParameter`	Action、Version 或请求字段不合法
400	`UnsupportedCapability`	没有可用的真人认证凭证
401	`Unauthorized`	AK/SK、签名、摘要、路径、查询参数或时间错误
403	`Forbidden`	凭证或用户已停用，或 IP 不在白名单
404	`ResourceNotFound`	资源不存在或不属于当前用户
500	`InternalError`	服务端内部错误

火山方舟官方素材库兼容接口使用说明

适用范围#

获取系统 AK/SK#

请求入口#

HMAC-SHA256 V4 鉴权#

Action 清单#

真人扫码授权#

上传、查询和生成#

创建普通素材组#

常见错误#