人像认证（真人活体认证）

SilvaMux 提供与火山引擎一致的「真人认证」人脸活体识别接口。客户可以拉起火山 H5 活体认证页面，完成本人认证后把正脸素材入库为真人素材（LivenessFace），再通过 asset://<Id> 在视频生成中引用，构成私域真人人像库的完整闭环：

拉起活体认证 H5 → 用户完成认证 → 回调 → 获取真人素材组 → 上传真人素材 → 生成视频

接口行为与火山引擎「管理私域素材库」一致（拉起真人认证 H5（CreateVisualValidateSession）），只是 Endpoint 指向本平台、鉴权凭证使用平台签发的 AK/SK。

接入准备

控制台 → 凭据管理 → 创建 Volcengine 兼容 (AK/SK) 凭据，一次性返回 AK 与 SK（SK 仅此时可见）。
AK/SK 绑定组织，项目通过 ProjectName 字段指定（留空或填 default 使用默认项目）。
使用火山引擎官方 SDK 或自定义 V4 签名，请求发送到本平台：

项	值
Endpoint	`https://www.silvamux.com/api/ark`
Region	`cn-beijing`
Service	`ark`
Version	`2024-01-01`
鉴权	火山 V4 签名，使用平台签发的 AK/SK
调用方式	`POST /api/ark?Action=<Action>&Version=2024-01-01`

整体流程

步骤	动作	接口	结果
①	发起真人认证	`CreateVisualValidateSession`	`H5Link` + `BytedToken`（会话 id）
②	用户打开 H5 完成活体认证	浏览器跳转，平台回调	自动跳回你的 `CallbackURL`，带 `bytedToken` + `resultCode`
③	确认认证结果并获取素材组	`GetVisualValidateResult`	生成并返回 `GroupId`（LivenessFace 真人素材组，一次性）
④	上传真人素材	`CreateAsset`（指向 ③ 的 `GroupId`）	返回真实上游素材 `Id`，轮询 `GetAsset` 至 `Active`
⑤	生成视频	视频生成接口	`content` 中用 `asset://<Id>` 引用

① 创建认证会话 CreateVisualValidateSession

POST /api/ark?Action=CreateVisualValidateSession&Version=2024-01-01

请求体：

字段	必填	说明
`CallbackURL`	是	认证完成后接收结果的回调地址，必须是 `http`/`https` URL
`ProjectName`	否	项目名；留空或 `default` 使用默认项目

{
  "CallbackURL": "https://your-host.example/callback",
  "ProjectName": "default"
}

请求使用平台签发的 AK/SK 做火山 V4 签名（Service=ark、Region=cn-beijing、Version=2024-01-01），具体签名方式见素材管理接入说明。

响应：

{
  "ResponseMetadata": {
    "RequestId": "3f2f8b4d1a6e4c5b9a7d0e2f1c3b4a5d",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "H5Link": "https://...（火山 H5 活体认证页面）",
    "BytedToken": "VVS-01JXXXXXXXXXXXXXX"
  }
}

字段	说明
`H5Link`	让用户在浏览器（手机/PC）打开的活体认证页面
`BytedToken`	平台会话 id，后续 `GetVisualValidateResult` 使用它作为 `BytedToken`

H5 链接仅能使用一次，会话有效期 30 分钟。

② 认证回调

用户打开 H5Link 完成眨眼/转头等活体动作后，火山引擎把用户浏览器重定向到平台回调；平台记录认证结果后，用一个 HTML 页面把浏览器自动跳转到你提供的 CallbackURL，并附加参数：

参数	说明
`bytedToken`	平台会话 id（与 ① 返回的 `BytedToken` 相同）
`resultCode`	`10000` 表示认证通过

你的回调服务可据此展示「认证结果」，随后调用 GetVisualValidateResult 正式获取素材组。

③ 获取真人素材组 GetVisualValidateResult

POST /api/ark?Action=GetVisualValidateResult&Version=2024-01-01

请求体：

字段	必填	说明
`BytedToken`	是	① 返回的会话 id

{
  "BytedToken": "VVS-01JXXXXXXXXXXXXXX"
}

响应：

{
  "ResponseMetadata": { "Action": "GetVisualValidateResult", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": { "GroupId": "group-01JXXXXXXXXXXXXXX" }
}

成功后平台会创建并返回一个 LivenessFace 真人素材组（GroupId），该组背后是真实的真人上游组，客户端无需知晓上游组 id。

行为	说明
一次性	成功后会话被销毁，不能重复使用
失败	会话不存在、过期或回调未到达，均返回 `401 InvalidVisualValidate`
有效期	30 分钟（自回调收到时起算）

④ 上传真人素材 CreateAsset

POST /api/ark?Action=CreateAsset&Version=2024-01-01

请求体：

字段	必填	说明
`GroupId`	是	③ 返回的 LivenessFace 组 id
`URL`	是	真人正脸素材的公网可访问 URL
`AssetType`	是	`Image` / `Video` / `Audio`
`Name`	否	素材名称；省略时由 URL 推导

{
  "GroupId": "group-01JXXXXXXXXXXXXXX",
  "URL": "https://your-host.example/face.jpg",
  "AssetType": "Image",
  "Name": "my-face"
}

响应：

{
  "ResponseMetadata": { "Action": "CreateAsset", "Version": "2024-01-01", "Service": "ark", "Region": "cn-beijing" },
  "Result": { "Id": "<真实上游素材 id>" }
}

平台按目标组的类型自动路由上游组：指向 LivenessFace 组即上传到真人上游组，无需（也不必）在请求里传 GroupType。指向普通 AIGC 组则按组织级 AIGC 组入库，二者不会混淆。需要组织具备 AVGV2 能力，否则返回 403 SubscriptionRequired。

⑤ 管理真人素材

查询状态 GetAsset

POST /api/ark?Action=GetAsset&Version=2024-01-01

请求体：{ "Id": "<素材 id>", "ProjectName": "default" }

响应 Result.Status：Processing / Active / Failed。创建后通常先 Processing，轮询直到 Active 才可用于视频生成。

列出素材 ListAssets

POST /api/ark?Action=ListAssets&Version=2024-01-01

请求体支持 Filter（GroupIds、GroupType、Statuses、Name）、分页（PageNumber/PageSize，最大 100）与排序（SortBy/SortOrder，如 SortBy=CreateTime&SortOrder=Desc）。Filter.GroupType 传 LivenessFace 可只列真人素材。

删除素材 DeleteAsset

POST /api/ark?Action=DeleteAsset&Version=2024-01-01

请求体：{ "Id": "<素材 id>", "ProjectName": "default" }。同步删除火山上游素材与本地记录。

在视频生成中引用

真人素材 Active 后，在视频生成的 content 中用 asset://<素材 id> 引用：

{
  "model": "<MODEL_CALL_NAME>",
  "content": [
    {"type": "image_url", "image_url": {"url": "asset://<素材 id>"}, "role": "reference_image"},
    {"type": "text", "text": "让画面中的角色跳舞"}
  ]
}

视频生成走自有接口 + API Key（sk_live_），不是 AK/SK 签名；model 使用模型广场的真实调用名。详见视频生成 API。

错误码

Code	含义
`InvalidSignature`	签名校验失败（AK/SK 错、请求被篡改、时钟偏移过大）
`InvalidVisualValidate`	认证会话无效、过期或认证未完成（`GetVisualValidateResult` 所有失败路径，HTTP 401）
`MissingParameter.` / `InvalidParameter.`	缺少必填字段 / 字段值非法（如 `CallbackURL` 非 http(s)、`AssetType` 非法）
`NotFound.project` / `NotFound.group_id` / `NotFound.asset_id`	项目 / 素材组 / 素材不存在
`SubscriptionRequired`	组织未开通相应能力（如 AVGV2）
`UpstreamError.Asset`	上游素材服务错误，透传上游原因，响应头带 `X-Upstream-Request-Id`
`InternalError`	服务内部错误，记录 `RequestId` 联系支持

注意事项

H5 一次性 + 30 分钟有效期：H5Link 只能使用一次，会话 30 分钟内有效；超时需重新创建会话。
回调地址必须公网可达：火山引擎通过浏览器跳转回调，localhost/内网地址不可用。
素材 URL 必须公网可访问：平台拉取素材入库，localhost/内网地址不可用。
素材为本人正脸：请遵守相关法律法规与平台服务条款，勿上传他人肖像素材。
素材按项目隔离：上传与查询需使用同一 ProjectName；视频生成需使用素材所在项目。

参考

本平台的素材管理与视频生成 API
火山引擎官方文档：拉起真人认证 H5（CreateVisualValidateSession）、私域真人人像素材资产使用指南