真人认证

创建真人认证素材组，完成手机实名认证后在组内管理可用于生成的真人素材。

最后更新: 2026-08-06

认证流程

1
创建认证
提交真人素材组名称，EaseRouter 同时创建本地素材组和认证记录。
2
完成手机认证
使用创建响应返回的 H5 链接或二维码，在 5 分钟内完成认证。
3
等待认证结果
EaseRouter 将持续同步认证结果，认证成功后即可使用对应的真人素材组。
4
添加真人素材
认证成功后，可以在该素材组中创建 image、video 和 audio 素材。

创建真人认证

POST/api/v1/verification/add

创建真人素材组和认证会话。

参数	类型	要求	说明
`groupName`	string	必填	真人素材组名称，1-40 个字符。
`description`	string	可选	素材组说明，最多 120 个字符。

{
  "groupName": "品牌人物素材",
  "description": "品牌主理人相关真人素材"
}

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": 3001,
    "assetGroupId": "group-2222222222222222222222222222222202",
    "status": "PENDING",
    "verificationUrl": "https://example.com/real-validate?token=rt_xxx",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAA...",
    "channels": [
      {
        "channelId": "channel-11111111111111111111111111111111",
        "status": "PENDING",
        "verificationUrl": "https://example.com/real-validate?token=rt_xxx",
        "qrCode": "data:image/png;base64,iVBORw0KGgoAAA...",
        "expiresAt": "2026-07-14 12:05:00"
      },
      {
        "channelId": "channel-22222222222222222222222222222222",
        "status": "WAITING_CONFIG",
        "expiresAt": "2026-07-14 12:05:00"
      }
    ],
    "expiresAt": "2026-07-14 12:05:00",
    "createdAt": "2026-07-14 12:00:00"
  }
}

字段	类型	说明
id	integer	真人认证数据库 ID。
assetGroupId	string	本次认证创建的真人素材组公开 ID，格式为 group-{32位小写无连字符UUID}{2位数字}。
status	string	认证聚合状态，创建后通常为 PENDING；部分处理通道成功时为 PARTIAL。
verificationUrl	string	channels 中首个可用的手机认证 H5 链接，保留用于兼容旧客户端，5 分钟内有效。
qrCode	string	与顶层 verificationUrl 对应的二维码，保留用于兼容旧客户端；具体格式由处理通道决定。
channels	array	匿名处理通道列表。新客户端应遍历此数组，并使用各项的 channelId 区分认证入口。
channels[].channelId	string	匿名且不可推断内部处理通道信息的认证入口 ID。
channels[].status	string	当前入口状态：WAITING_CONFIG、PENDING、SUCCEEDED、FAILED 或 EXPIRED。
channels[].verificationUrl	string	当前入口的短期 H5 链接，仅在待认证且未过期时返回。
channels[].qrCode	string	当前入口的短期二维码，仅在待认证且未过期且处理通道提供时返回。
channels[].expiresAt	datetime	当前入口的平台认证窗口时间。WAITING_CONFIG 不会因该时间到达而终止；配置就绪并创建入口后会重新计算。
expiresAt	datetime	H5 链接和二维码的失效时间。
completedAt	datetime	认证结束时间；未结束时省略。
createdAt	datetime	认证记录创建时间。

创建真人素材管理 H5

POST/api/v1/verification/createH5

为当前 API Key 所属账户创建处理通道真人素材管理 H5 地址；请求体为空。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "h5Link": "https://example.com/real-validate/h5?token=rt_xxx",
    "expiresIn": 300
  }
}

字段	类型	说明
h5Link	string	处理通道真人素材管理 H5 地址，包含敏感的短期访问凭证。
expiresIn	integer	链接有效秒数；小于等于 0 表示处理通道声明长期有效。

查询认证结果

GET/api/v1/verification/detail/{id}

按正整数 ID 查询当前账户的认证状态。异步消费者负责查询并同步认证结果。

{
  "code": "SUCCESS",
  "msg": "操作成功",
  "result": {
    "id": 3001,
    "assetGroupId": "group-2222222222222222222222222222222202",
    "status": "PARTIAL",
    "verificationUrl": "https://example.com/real-validate?token=rt_yyy",
    "qrCode": "data:image/png;base64,iVBORw0KGgoBBB...",
    "channels": [
      {
        "channelId": "channel-11111111111111111111111111111111",
        "status": "SUCCEEDED",
        "expiresAt": "2026-07-14 12:05:00"
      },
      {
        "channelId": "channel-22222222222222222222222222222222",
        "status": "PENDING",
        "verificationUrl": "https://example.com/real-validate?token=rt_yyy",
        "qrCode": "data:image/png;base64,iVBORw0KGgoBBB...",
        "expiresAt": "2026-07-14 12:05:00"
      }
    ],
    "expiresAt": "2026-07-14 12:05:00",
    "createdAt": "2026-07-14 12:00:00"
  }
}

补充认证入口

POST/api/v1/verification/sync/{id}

为历史认证记录补充创建后新增的匿名处理通道入口；请求体为空。

响应结构与查询认证结果一致。仅在存在新增入口时重新开启 5 分钟认证窗口；重复调用不会重复创建已有 channelId。

认证状态

状态	说明
PENDING	尚无处理通道认证成功，且至少一个入口正在等待配置、等待用户认证或等待结果同步。
PARTIAL	至少一个处理通道认证成功，但并非全部成功；真人素材组已经可用，其余入口可能仍在等待或已经失败。
SUCCEEDED	所有处理通道均认证成功，真人素材组已可用于创建图片、视频和音频素材。
FAILED	认证流程发生不可恢复的错误，当前认证已结束。
EXPIRED	认证 H5 会话已超过 5 分钟且尚未完成，需要重新创建。

真人素材组规则

任一处理通道认证成功前不能向该素材组创建素材，当前返回 code=FAIL、msg=真人素材组尚未认证成功。
认证成功后，该真人素材组按长期有效处理，并由 EaseRouter 统一维护。
真人素材组与普通素材组一样支持 image、video 和 audio 三种素材类型。
同一账户可以重复发起认证，每次认证创建一个独立的真人素材组。

真人认证业务失败

HTTP	业务 code	当前 msg 场景
200	FAIL	真人认证处理通道不可用、处理通道返回无效结果，或认证记录不存在。
200	INTERNAL_SERVER_ERROR	未处理的程序异常。