跳到主要内容

真人素材与认证

真人素材指含真人人脸的图片、视频等素材。与虚拟素材不同,真人素材必须先完成真人认证,平台才会建立真人分组;只能向已验证的真人分组上传素材。

本文说明真人认证的完整流程、各环节的判断依据与常见失败原因。虚拟素材(不含真人人脸)的入库流程见火山方舟素材库。

使用前必读
  • 真人认证通过 H5 认证链接完成,链接供终端用户打开。
  • 一个账号下可以有多个真人分组。
  • 认证链接有效期 30 分钟,过期需要重新发起。
  • 真人素材只能归属认证时对应的素材资源,不能跨资源使用。

与虚拟素材的区别​

维度虚拟素材(AIGC)真人素材(LivenessFace)
分组建立方式调用创建分组主动创建完成真人认证后平台自动建立,没有创建接口
前置条件无必须先通过真人认证拿到分组 ID
分组类型标识GroupType=AIGCGroupType=LivenessFace
分组 ID 形态平台数字 ID,如 2113257314734424065group-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 只是快照,建议仍调用一次查询接口确认最终结果。

在控制台完成认证与上传​

  1. 登录 ClawdRouter 控制台,在左侧导航进入「素材库」,切到顶部的真人素材标签页。

    素材库「真人素材」标签页

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

    「真人认证入口」弹窗

    弹窗中的「适用模型」即响应的 ModelIds,「人物姓名或编号」即请求的 GroupName;点击生成二维码时会调用发起真人认证。

  3. 把二维码或链接交给素材中的本人,由其本人完成认证。认证链接 30 分钟内有效。

    如果一直没有结果,回到弹窗点查询认证结果确认状态,对应查询真人认证结果。

  4. 认证通过后,点击页面右上角的上传真人素材,选择所属人物、素材属性与文件后上传。

    「上传真人素材」弹窗

    上传后可在列表的「入库状态」列查看进度。

管理真人分组​

点击工具栏的人物管理,在「真人认证与人物」弹窗中查看已认证的人物列表,可编辑或删除。

「真人认证与人物」弹窗

删除将删除该认证组及其中的真人素材,厂商侧组内素材也会删除;已转存的 OSS 原件保留。

删除前先确认

一个账号下可以有多个认证组,删除时请核对「人物名称」与「分组 ID」,避免误删。删除动作不可撤销。

查询真人分组与素材​

两类查询发往同一路径,只有 Action 不同:

查询对象查询参数
真人分组Action=ListAssetGroups&Version=2024-01-01
真人素材Action=ListAssets&Version=2024-01-01

请求体两者的写法相同,用 GroupType=LivenessFace 配合 GroupIds 筛选;完整字段见查询分组列表与查询素材列表。

限制与注意事项​

  • 真人素材不能跨资源使用。 素材只能归属认证时对应的素材资源。
  • 不能通过创建分组建真人分组。 该接口只支持 AIGC 类型。
  • 删除真人分组会级联删除组内素材,同时保留 OSS 原件。
  • 认证链接过期后旧链接扫码会失败,必须重新调用发起真人认证获取新链接。
  • 上传成功不等于可用:与虚拟素材一样,CreateAsset 返回成功只表示已受理,需等 Status 变为 Active。
  • 一次性素材在模型调用后自动删除,永久素材长期保留。 一次性素材被消费后只回收素材,不删除真人分组。

相关链接​