跳到主要内容

真人人像素材库接入流程

真人人像素材库使用 LivenessFace 素材组。本人先通过 H5 完成认证，平台生成素材组，再向该组添加素材并等待处理完成，最后通过平台素材 ID 发起视频生成。

鉴权说明

用户控制台接口，使用登录会话 Cookie，或请求头 Authorization: <access_token>。访问令牌由 生成访问令牌 获取，与模型调用使用的 sk- 密钥不同。

接入步骤​

  1. 选择 普通认证 或 自定义回调认证，提交素材组名称及可选描述。
  2. 保存返回的会话 ID，将 h5Link 交给本人打开认证。当前会话有效期为创建后 120 秒，以 expiresAt 为准。
  3. 查询认证会话，等待 status=Succeeded，获取平台 groupId。自定义回调模式会通过浏览器跳转客户页面。
  4. 创建真人素材，显式传入该 groupId、groupType=LivenessFace、素材 URL 和类型。
  5. 查询真人素材详情，等待 status=Active 且 assetStatus=1 后，使用 asset://<平台素材 ID> 调用 火山视频生成接口。模型需支持相应素材类型和角色。
创建认证会话 → 本人打开 H5 认证 → 平台处理结果并生成 LivenessFace 素材组
                                              ↓
查询会话取得 groupId → 创建真人素材 → 查询至 Active → asset:// 引用生成视频

与虚拟人像素材库的区别​

项目真人人像虚拟人像
groupTypeLivenessFaceAIGC
素材组来源本人 H5 认证成功后生成，请通过认证流程创建普通创建素材组接口
创建素材必须指定认证所得 groupId；只支持 URL支持 URL 或 multipart 文件
认证与审核认证成功后仍需等待素材处理为 Active创建后等待素材处理为 Active

当前真人认证仅支持平台已配置且当前用户可用的火山官方渠道；用户请求不指定 channelId、channelConfigId 或 projectName，由平台选择。未配置可用官方渠道时无法发起认证。

会话状态​

状态含义与处理
Pending等待本人完成 H5 认证；未过期时返回 h5Link
Processing会话状态枚举中的处理中状态；若返回请继续查询
Succeeded认证成功并生成平台素材组；查询时已删除的组不再返回 groupId
Failed认证或处理失败，查看 errorCode/errorMessage，排除原因后新建会话
Expired等待认证时已过期，请新建会话

认证会话状态与素材的 Processing / Active / Failed 处理状态是两套状态。resultCode=10000 只说明 H5 认证成功，最终能否取得素材组应以会话 status 和 groupId 为准。

接口目录​

方法接口
POST创建真人认证会话
POST创建真人认证会话（自定义回调）
GET查询真人认证会话
GET查询真人认证会话列表
POST创建真人素材
GET查询真人素材列表
GET查询真人素材详情
PUT更新真人素材
DELETE删除真人素材
GET查询真人素材组列表
GET查询真人素材组详情
PUT更新真人素材组
DELETE删除真人素材组

结果字段与错误处理​

  • 普通创建接口使用 sessionId，自定义回调创建接口使用 platformSessionId；两个查询接口统一返回 sessionId。
  • 会话中的 groupId、客户跳转参数 assetGroupId、素材组详情中的 id 表示同一个平台素材组 ID。不要使用火山上游 ID 替代它。
  • 本目录 JSON 示例均为真实请求体结构，参数直接放在顶层，无需 body 包装。列表使用 pageNumber / pageSize。
  • 成功响应为 success=true、message=""、data；业务失败通常仍返回 HTTP 200，但 success=false。缺少登录身份可返回 HTTP 401。必须同时检查 HTTP 状态与 success。
  • 认证回调入口由 H5 使用，地址由平台自动生成，业务系统无需自行调用。客户回调参数应通过带鉴权的会话查询核验。
{
  "success": false,
  "message": "具体错误说明"
}

常见原因包括参数缺失、缺少可用官方渠道、回调地址不符合要求、会话过期、资源不存在或无权访问，以及上游处理失败。请根据 message 或会话/素材的错误字段处理。