真人素材与认证
真人素材指含真人人脸的图片、视频等素材。与虚拟素材不同,真人素材必须先完成真人认证,平台才会建立真人分组;只能向已验证的真人分组上传素材。
本文说明真人认证的完整流程、各环节的判断依据与常见失败原因。虚拟素材(不含真人人脸)的入库流程见火山方舟素材库。
- 真人认证通过 H5 认证链接完成,链接供终端用户打开。
- 一个账号下可以有多个真人分组。
- 认证链接有效期 30 分钟,过期需要重新发起。
- 真人素材只能归属认证时对应的素材资源,不能跨资源使用。
与虚拟素材的区别
| 维度 | 虚拟素材(AIGC) | 真人素材(LivenessFace) |
|---|---|---|
| 分组建立方式 | 调用创建分组主动创建 | 完成真人认证后平台自动建立,没有创建接口 |
| 前置条件 | 无 | 必须先通过真人认证拿到分组 ID |
| 分组类型标识 | GroupType=AIGC | GroupType=LivenessFace |
| 分组 ID 形态 | 平台数字 ID,如 2113257314734424065 | group-xxx,如 group-20261112100048-z5wk7 |
| 额外字段 | 无 | AuthorizedAt、ModelIds |
| 上传时 GroupId | 可选,不传表示未分组 | 必填,且必须是已验证的真人分组 ID |
除上述差异外,两类素材共用同一套上传、查询、更新、删除接口。
整体流程
真人认证分三步:发起认证 → 本人完成认证 → 拿到分组 ID 后上传素材。
第 1 步:发起认证
调用发起真人认证,得到 H5Link 与 BytedToken。CallbackURL、GroupName 都可选,不传时认证结束仍会建组,分组名默认为分组 ID。
第 2 步:本人完成认证
把 H5Link 交给素材中的本人打开并完成认证,无法代为操作。认证链接 30 分钟内有效。
第 3 步:拿到分组 ID 并上传
用 BytedToken 调用查询真人认证结果。认证未完成时 GroupId 为 null(不报错),建议每 5 秒轮询一次。
拿到 GroupId 后调用上传素材,把它传入 GroupId。之后用查询素材详情轮询到 Status 为 Active 即可使用。
配置 CallbackURL 后,认证结束平台会以浏览器跳转(GET)方式打开该地址,并追加 bytedToken、status、groupId、message 参数。status 只是快照,建议仍调用一次查询接口确认最终结果。
在控制台完成认证与上传
-
登录 ClawdRouter 控制台,在左侧导航进入「素材库」,切到顶部的真人素材标签页。

-
点击工具栏的发起真人认证,填写人物姓名或编号(可不填),点击生成二维码。

弹窗中的「适用模型」即响应的
ModelIds,「人物姓名或编号」即请求的GroupName;点击生成二维码时会调用发起真人认证。 -
把二维码或链接交给素材中的本人,由其本人完成认证。认证链接 30 分钟内有效。
如果一直没有结果,回到弹窗点查询认证结果确认状态,对应查询真人认证结果。
-
认证通过后,点击页面右上角的上传真人素材,选择所属人物、素材属性与文件后上传。

上传后可在列表的「入库状态」列查看进度。
管理真人分组
点击工具栏的人物管理,在「真人认证与人物」弹窗中查看已认证的人物列表,可编辑或删除。

删除将删除该认证组及其中的真人素材,厂商侧组内素材也会删除;已转存的 OSS 原件保留。
一个账号下可以有多个认证组,删除时请核对「人物名称」与「分组 ID」,避免误删。删除动作不可撤销。
查询真人分组与素材
两类查询发往同一路径,只有 Action 不同:
| 查询对象 | 查询参数 |
|---|---|
| 真人分组 | Action=ListAssetGroups&Version=2024-01-01 |
| 真人素材 | Action=ListAssets&Version=2024-01-01 |
请求体两者的写法相同,用 GroupType=LivenessFace 配合 GroupIds 筛选;完整字段见查询分组列表与查询素材列表。
限制与注意事项
- 真人素材不能跨资源使用。 素材只能归属认证时对应的素材资源。
- 不能通过创建分组建真人分组。 该接口只支持
AIGC类型。 - 删除真人分组会级联删除组内素材,同时保留 OSS 原件。
- 认证链接过期后旧链接扫码会失败,必须重新调用发起真人认证获取新链接。
- 上传成功不等于可用:与虚拟素材一样,
CreateAsset返回成功只表示已受理,需等Status变为Active。 - 一次性素材在模型调用后自动删除,永久素材长期保留。 一次性素材被消费后只回收素材,不删除真人分组。
相关链接
- 常见问题 - 上传、认证与素材状态等问题
- 火山方舟素材库 API 概览 - 认证、签名与接口索引
- 火山方舟素材库 - 虚拟素材的入库流程与格式要求
- 视频生成 - 提交视频生成任务并引用素材