真人素材 API 接口文档（H5 人脸认证）

真人素材用于生成"数字人 / 真人形象"类视频。与普通素材不同，真人素材上传前必须先完成 H5 人脸认证授权：授权方在 H5 页面刷脸成功后，系统会创建一个真人素材组（艺人组），后续上传到该组的素材会被上游做人脸一致性校验——只有与授权刷脸为同一个人的素材才能通过审核。

审核通过后同样获得 asset:// 引用地址，可直接用于视频生成。

整体流程

1. 获取 H5 认证链接   POST /v1/assets/real-person/auth/link  （提交艺人名称）
        │
        ▼
2. 授权方刷脸        打开返回的 h5_url，在 120 秒内完成人脸认证
        │
        ▼
3. 查询艺人组        GET  /v1/assets/real-person/groups      （拿到真人组 group_id）
        │
        ▼
4. 上传真人素材      POST /v1/assets                          （传真人组 group_id，触发人脸校验）
        │
        ▼
5. 用于视频生成      asset:// 引用地址传入 /v1/video/generations

（可选）清理素材    POST /v1/assets/real-person/assets/delete   删单个真人素材
（可选）清理整组    POST /v1/assets/real-person/groups/delete   删整个真人素材组（连同组内素材）

⚠️ H5 认证链接有效期 120 秒，且使用一次后失效，超时需重新调用第 1 步获取新链接。

令牌隔离机制

真人素材组按**令牌（Token）**隔离：用哪个令牌的 API Key 发起认证，艺人组就归属该令牌，其他令牌不可见、不可用。每次授权都会为该令牌创建一个独立的真人素材组，不同令牌即使认证同一位艺人，也会得到不同的 group_id。

认证方式

所有接口在请求头携带 API Key：

Authorization: Bearer sk-xxxx
Content-Type: application/json

基础地址

{BASE_URL}/v1/assets

1. 获取真人认证 H5 链接

提交艺人名称与描述，申请一个真人认证 H5 页面链接。授权方需在 120 秒内打开该链接完成人脸认证。

请求

POST /v1/assets/real-person/auth/link

请求参数

参数	类型	必填	说明
artist_name	string	是	艺人（授权组）名称，最多 32 字符，不可重复
artist_desc	string	否	艺人描述，最多 300 字符

请求示例

响应示例

{
  "code": "success",
  "data": {
    "h5_url": "https://h5-v2.kych5.com?...",
    "tip": "请让授权方在 120 秒内打开并完成认证，链接使用后失效"
  }
}

响应字段说明

字段	说明
h5_url	真人认证页面链接，有效期 120 秒，使用一次后失效
tip	使用提示

说明

请将 h5_url 转交授权方（真人本人），让其在手机上打开并在 120 秒内完成人脸认证。

链接用后即失效；超时或需重新认证时，重新调用本接口获取新链接。

认证成功后，系统自动为当前令牌创建真人素材组，随后可通过「2. 查询真人素材组」拿到 group_id。

错误响应

场景	响应
艺人名称为空	`{"error":{"message":"artist_name 不能为空"}}`
艺人名称过长	`{"error":{"message":"artist_name 最多支持 32 个字符"}}`
艺人描述过长	`{"error":{"message":"artist_desc 最多支持 300 个字符，请缩短描述后重试"}}`
未配置真人素材渠道	`{"error":{"message":"未找到可用的火山素材渠道..."}}`
创建授权链接失败	`{"error":{"message":"创建真人授权链接失败"}}`

2. 查询真人素材组

查询当前令牌已授权成功的真人素材组（艺人组）列表。授权方完成刷脸后调用本接口，即可拿到用于上传真人素材的 group_id。

请求

GET /v1/assets/real-person/groups

请求参数

无需请求体。

请求示例

响应示例

{
  "code": "success",
  "data": {
    "items": [
      {
        "id": 128,
        "group_id": "group-20260427120029-b2sks",
        "artist_name": "张三",
        "artist_desc": "品牌代言人真人素材组",
        "authorized_at": "2026-04-27T12:00:29+08:00",
        "asset_count": 3
      }
    ]
  }
}

响应字段说明

字段	说明
id	平台真人素材组 ID，上传真人素材时作为 `group_id` 传入（见「3. 上传真人素材」）
group_id	上游真实素材组标识（`group-xxx`），仅供参考展示
artist_name	创建认证链接时填写的艺人名称
artist_desc	艺人描述
authorized_at	授权成功时间
asset_count	该组已有素材数量

说明

上传真人素材时使用的是 id（平台组 ID，整数），不是上游 group_id 字符串。

若刚完成刷脸但列表为空，可稍等 1～2 秒重试；列表始终为空通常表示人脸认证未成功或链接已超时，请重新走「1. 获取真人认证 H5 链接」。

3. 上传真人素材

真人素材上传复用普通素材上传接口 POST /v1/assets，只需把 group_id 指定为「2. 查询真人素材组」返回的真人组 id。系统识别到真人组后，会向上游透传真人组标识，触发人脸一致性校验。

支持同步（sync，默认）与异步（async）两种模式，参数与普通素材上传完全一致，详见《素材库 API 接口文档》。以下以同步为例。

请求

POST /v1/assets

请求参数

参数	类型	必填	说明
url	string	是	素材文件的公网可访问 URL（须为该真人的正脸素材）
asset_type	string	是	素材类型：`Image`、`Video`、`Audio`
group_id	int	是	真人素材组 ID，即「2. 查询真人素材组」返回的 `id`
name	string	否	素材名称（上限 64 字符）
upload_mode	string	否	`sync`（默认）/ `async`

请求示例

响应示例（成功）

{
  "code": "success",
  "data": {
    "id": "asset-20260427120130-ngtck",
    "asset_url": "asset://asset-20260427120130-ngtck"
  }
}

响应示例（人脸不匹配）

当上传素材与授权刷脸不是同一个人时，上游返回人脸校验失败：

{
  "error": {
    "message": "FaceMismatch: 上传素材与授权认证人脸不一致"
  }
}

说明

asset_url：真人素材引用地址（asset://{id}），审核通过后可直接用于视频生成。

上传素材必须与授权刷脸为同一个人，否则返回 FaceMismatch 失败。

同一真人素材组只应上传同一位真人的素材，请勿混用不同艺人。

若 group_id 传的是普通分组（非真人组），则走普通上传逻辑，不会触发人脸校验。

素材要求（图片高度 300px~6000px、URL 公网可访问等）与普通素材一致。

错误响应

场景	响应
group_id 非当前令牌真人组	`{"error":{"message":"该 group_id 不属于当前用户或尚未授权成功"}}`
人脸不匹配	`{"error":{"message":"FaceMismatch: ..."}}`
素材 URL 不合法	`{"error":{"message":"第1条URL文件类型不受支持..."}}`
分组不存在/无权访问	`{"error":{"message":"指定的分组不存在或无权访问"}}`

4. 删除真人素材

删除真人素材组内的单个素材。真人素材是上游实体，删除会同时回调上游移除该素材，并清理平台本地记录。

⚠️ 真人素材删除不可恢复，且是永久从上游与平台一并移除。请确认素材确实不再需要后再调用。

请求

POST /v1/assets/real-person/assets/delete

请求参数

参数	类型	必填	说明
id	string	是	素材 ID，即「3. 上传真人素材」返回的 `id`（形如 `asset-xxx`，不含 `asset://` 前缀）

请求示例

响应示例（成功）

{
  "code": "success",
  "data": {
    "id": "asset-20260427120130-ngtck"
  }
}

说明

仅能删除属于当前令牌的真人素材，id 不属于当前用户时返回「素材不存在」。

该素材在上游若已被删除（无对应实体），仍按成功处理并清理本地记录（幂等）。

删除后素材的 asset:// 引用地址即刻失效，请勿再用于视频生成。

错误响应

场景	HTTP	响应
素材不属于当前令牌/不存在	404	`{"error":{"message":"素材不存在"}}`
上游删除失败	500	`{"error":{"message":"删除上游真人素材失败: ..."}}`

5. 删除真人素材组

删除整个真人素材组（艺人组）。平台会先向上游逐个删除组内全部素材，再删除该组，最后清理平台本地记录。

⚠️ 删除真人素材组会连同组内所有素材一并永久移除，且不可恢复。请务必确认整组素材都不再需要后再调用。

请求

POST /v1/assets/real-person/groups/delete

请求参数

参数	类型	必填	说明
id	int	是	平台真人素材组 ID，即「2. 查询真人素材组」返回的 `id`（整数）

请求示例

响应示例（成功）

{
  "code": "success"
}

说明

传入的 id 是「2. 查询真人素材组」返回的平台组 ID（整数），不是上游 group_id 字符串。

本接口仅用于删除真人素材组；若传入的是普通分组（非真人组），会被拒绝并提示改用普通分组删除接口 /v1/assets/groups/delete。

平台会自动清空组内素材后再删组，无需先手动逐个删除素材。

上游若已无对应组，仍按成功处理并清理本地记录（幂等）。

错误响应

场景	HTTP	响应
组不属于当前令牌/不存在	400	`{"error":{"message":"分组不存在"}}`
传入的是普通分组（非真人组）	400	`{"error":{"message":"该接口仅用于删除真人素材组，普通分组请走 /groups/delete"}}`
上游删除失败	500	`{"error":{"message":"删除上游真人素材组失败: ..."}}`

6. 在视频生成中使用真人素材

真人素材审核通过（status=Active）后，与普通素材一样通过 asset:// 地址在视频生成中引用：

视频生成的完整参数、素材引用类型（reference_image / first_frame / reference_video 等）与查询结果，详见《素材库 API 接口文档》第 9 节。

完整流程示例（Python）

演示：获取认证链接 → 等待刷脸 → 查询真人组 → 上传真人素材 → 等待就绪 → 生成视频。

注意事项

H5 认证链接有效期 120 秒、用后失效，超时需重新获取。

每次授权创建一个独立真人素材组；不同令牌、不同次授权即使同一艺人，group_id 也不同。

真人素材组按令牌隔离，上传时的 group_id 必须属于当前令牌，否则被拒绝。

同一真人素材组只应上传同一位真人的素材。

上传真人素材时上游做人脸一致性校验，素材与授权刷脸不一致会返回 FaceMismatch 失败。

不指定真人组 group_id（用普通分组）时，走普通素材逻辑，不进入真人素材组、不触发人脸校验。

错误码

HTTP 状态码	错误信息	说明
400	artist_name 不能为空	获取认证链接时未传艺人名称
400	artist_name 最多支持 32 个字符	艺人名称超长
400	artist_desc 最多支持 300 个字符	艺人描述超长
400	该 group_id 不属于当前用户或尚未授权成功	上传时真人组不属于当前令牌，或未授权成功
400	请选择令牌	查询真人组时未识别到令牌
404	素材不存在	删除真人素材时 `id` 不属于当前令牌或不存在
400	分组不存在	删除真人素材组时 `id` 不属于当前令牌或不存在
400	该接口仅用于删除真人素材组	删除组接口传入了普通分组（非真人组）
403	未找到可用的火山素材渠道	管理员未为该令牌所在分组配置真人素材渠道
500	FaceMismatch	上传素材与授权认证人脸不一致
500	创建真人授权链接失败	上游创建授权链接失败
500	删除上游真人素材失败 / 删除上游真人素材组失败	上游删除接口调用失败

真人素材 API 接口文档（H5 人脸认证）

整体流程#

令牌隔离机制#

认证方式#

基础地址#

1. 获取真人认证 H5 链接#

2. 查询真人素材组#

3. 上传真人素材#

4. 删除真人素材#

5. 删除真人素材组#

6. 在视频生成中使用真人素材#

完整流程示例（Python）#

注意事项#

错误码#

整体流程

令牌隔离机制

认证方式

基础地址

1. 获取真人认证 H5 链接

2. 查询真人素材组

3. 上传真人素材

4. 删除真人素材

5. 删除真人素材组

6. 在视频生成中使用真人素材

完整流程示例（Python）

注意事项

错误码