素材库透传网关

火山方舟(Volcengine Ark)私域素材库透传网关 · Version 2024-01-01

概述

本网关把火山方舟私域素材库的素材动作统一收口到一个入口,并做鉴权、ID 脱敏、参数校验、日志留痕后原样透传给火山上游。

• 所有素材动作统一走 POST /v1/volc/ark,靠 query 参数 Action 分流。
• 公共 query 固定携带 Version=2024-01-01(省略时网关自动补全)。
• 请求体为 JSON,字段与所选 Action 对应。
• 响应为火山上游原始结构:ResponseMetadata + Result。

鉴权

除 H5 真人认证回调外,所有接口都需要平台分发的 Bearer Token。放在请求头:

Authorization: Bearer <你的令牌>

缺失、格式错误或无效的令牌会返回 401 Unauthorized。

ID 规则(重要)

客户端只使用平台脱敏 ID,绝不能传火山真实 ID:

平台托管字段(无需传入)

ProjectName、CallbackURL 由平台按渠道 / 访问域名自动生成并强制注入。这些字段不作为请求参数,传入会被忽略。

工作流 A · 虚拟人像(AIGC)

虚拟人像素材可直接建组入库,无需人脸认证。

1. 建分组 —— CreateAssetGroup(GroupType=AIGC),拿到 hbg- 分组 ID。
2. 入库素材 —— CreateAsset 传公网 URL,拿到 hb- 素材 ID,状态为 Processing。
3. 轮询状态 —— GetAsset 直到 Status=Active(或 Failed)。
4. 使用 —— 仅 Active 素材可用于后续视频生成。

工作流 B · 真人人像(LivenessFace)

真人人像不能直接建组,必须先走 H5 真人认证。

1. 发起认证 —— CreateVisualValidateSession(请求体留空),拿到 H5Link + session_id。
2. 用户认证 —— 用户在 H5Link 完成人脸认证,浏览器自动回跳并完成建组。
3. 入库素材 —— 向该真人组 CreateAsset,上游会做人脸比对,不一致则 Failed。
4. 轮询状态 —— GetAsset 直到 Active。

Action 一览

下列 Action 均为 POST /v1/volc/ark?Action=<名称>&Version=2024-01-01。

分组接口

CreateAssetGroup · 建分组

虚拟人像 AIGC 直接建组;真人人像走 CreateVisualValidateSession。响应中的 GroupId 会被翻译为 hbg-。

curl -X POST 'https://<host>/v1/volc/ark?Action=CreateAssetGroup&Version=2024-01-01' \
  -H 'Authorization: Bearer <令牌>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Name": "美妆博主A",
    "Description": "美妆类素材",
    "GroupType": "AIGC"
  }'

字段: Name(必填,≤64 字符)、Description(选填,≤300 字符)、GroupType(选填,当前仅 AIGC)。

GetAssetGroup / UpdateAssetGroup / DeleteAssetGroup

# 查询分组
{ "GroupId": "hbg-3V1lztXLe9Wzj399OyLm" }

# 更新分组(名称 / 描述)
{ "GroupId": "hbg-3V1lztXLe9Wzj399OyLm", "Name": "改名后的组", "Description": "新描述" }

# 删除分组
{ "GroupId": "hbg-3V1lztXLe9Wzj399OyLm" }

素材接口

CreateAsset · 入库素材

平台不收二进制,只收公网可访问 URL,原样交火山入库。返回 hb- 素材 ID,状态 Processing,需轮询至 Active。真人组入库会做人脸比对。

curl -X POST 'https://<host>/v1/volc/ark?Action=CreateAsset&Version=2024-01-01' \
  -H 'Authorization: Bearer <令牌>' \
  -H 'Content-Type: application/json' \
  -d '{
    "GroupId": "hbg-3V1lztXLe9Wzj399OyLm",
    "URL": "https://example.com/face.jpg",
    "AssetType": "Image",
    "Name": "正脸照"
  }'

响应:

{
  "ResponseMetadata": { "Action": "CreateAsset", "RequestId": "...", "Region": "cn-beijing", "Service": "ark", "Version": "2024-01-01" },
  "Result": { "Id": "hb-yyyyyyyy" }
}

字段: GroupId、URL、AssetType(Image/Video/Audio)必填;Name 选填,仅供检索,不进推理。URL 的可访问性与时效由调用方自保。

GetAsset · 轮询状态

轮询 Status:Processing → Active / Failed,仅 Active 可用于视频生成。返回的 URL 为火山 12h 预览地址,平台不持久化。

# 请求
{ "Id": "hb-MnP48NWmWCa3S3zYJNZ9" }

# 响应 Result 摘要
{
  "Id": "hb-MnP48NWmWCa3S3zYJNZ9",
  "GroupId": "hbg-3V1lztXLe9Wzj399OyLm",
  "AssetType": "Image",
  "Status": "Active",
  "Name": "人脸照-2",
  "URL": "https://ark...(12h 预览)",
  "CreateTime": "2026-06-22T08:06:23Z",
  "UpdateTime": "2026-06-22T08:06:26Z"
}

ListAssets · 列出素材

过滤条件统一放进 Filter 对象(必填)。顶层 GroupId 不被识别,会报 MissingParameter.Filter。Filter.GroupIds 为字符串数组,元素须为 hbg-。

{
  "Filter": {
    "GroupIds": ["hbg-3V1lztXLe9Wzj399OyLm"],
    "GroupType": "LivenessFace",
    "Statuses": ["Active", "Processing"],
    "Name": "figure"
  },
  "PageNumber": 1,
  "PageSize": 10,
  "SortBy": "GroupId",
  "SortOrder": "Asc"
}

说明: GroupType 真人用 LivenessFace、虚拟用 AIGC;Statuses 支持 Active/Processing/Failed;Name 模糊搜索。响应 Result.Items[] 每条的 Id/GroupId 均已脱敏。

UpdateAsset / DeleteAsset

# 更新素材(如改备注名)
{ "Id": "hb-yyyyyyyy", "Name": "renamed-asset" }

# 删除素材
{ "Id": "hb-yyyyyyyy" }

真人认证

CreateVisualValidateSession · 发起真人 H5 认证

真人人像建组入口。请求体留空即可。CallbackURL / session_id 由平台服务端按访问域名生成;ProjectName 由平台强制注入;BytedToken 由后端持有不下发。响应只回 H5Link + session_id。

curl -X POST 'https://<host>/v1/volc/ark?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H 'Authorization: Bearer <令牌>' \
  -H 'Content-Type: application/json' \
  -d '{}'

用户在返回的 H5Link 完成人脸认证后,浏览器自动跳转完成建组。

错误处理