跳到主要内容

创建真人认证会话（自定义回调）

POST /api/volc-user/visual-validate-sessions/custom-callback

生成 H5 认证链接，认证结果由平台处理后，浏览器通过 HTTP 302 跳转到客户系统。

鉴权说明

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

请求参数​

参数名类型必选说明
namestring必选认证成功后素材组的名称，去除首尾空白后不能为空
descriptionstring可选认证成功后素材组的描述
customCallbackURLstring必选客户接收接口的完整 http/https 地址；允许与平台使用同一 hostname，仍须符合平台 URL 访问策略

请求示例​

POST /api/volc-user/visual-validate-sessions/custom-callback
Authorization: <access_token>
Content-Type: application/json

{
  "name": "演员本人素材组",
  "description": "用于授权的视频生成",
  "customCallbackURL": "https://customer.example.com/verification/done?orderId=demo-001"
}

响应字段（200）​

字段名类型说明
successboolean业务是否成功；HTTP 200 仍需检查此字段
messagestring提示信息，成功时为空字符串
dataobject成功时的响应数据
data.platformSessionIdstring平台认证会话 ID，用于查询认证结果
data.statusstringPending、Processing、Succeeded、Failed、Expired，见 接入流程
data.h5Linkstring仅在会话为 Pending 且未过期时返回；交给本人打开完成认证
data.expiresAtinteger认证链接过期时间，Unix 秒；当前会话有效期为创建后 120 秒
data.groupIdstring认证成功后生成的平台素材组 ID；无值时省略，查询时已删除的素材组也不再返回
data.resultCodestringH5 认证结果码，有值时返回；成功为 10000
data.errorCodestring错误码，有值时返回
data.errorMessagestring错误说明，有值时返回
data.createTimeinteger创建时间，Unix 秒
data.updateTimeinteger更新时间，Unix 秒
data.customerRedirectURLstring完成认证后用于跳转客户系统的地址；Pending 时省略

响应示例​

{
  "success": true,
  "message": "",
  "data": {
    "platformSessionId": "vvs-example",
    "status": "Pending",
    "expiresAt": 1792022520,
    "createTime": 1792022400,
    "updateTime": 1792022400,
    "h5Link": "https://example.com/visual-validate?token=example"
  }
}

客户回调参数​

当前实现通过浏览器 302 跳转携带以下 Query 参数，不发送服务端 Webhook。客户地址原有 Query 参数会保留；请避免预设下表中的保留参数。

参数名说明
platformSessionId创建接口返回的平台会话 ID
status会话状态，成功为 Succeeded，认证或处理失败为 Failed
resultCodeH5 结果码，成功为 10000；某些处理失败也可能保留此码，应结合 status 判断
assetGroupId成功时附加的平台素材组 ID，与查询接口的 groupId 对应
errorCode / errorMessage失败时附加的错误码与说明
GET /verification/done?orderId=demo-001&platformSessionId=vvs-example&status=Succeeded&resultCode=10000&assetGroupId=group-example

创建接口返回 platformSessionId；查询单个会话和会话列表统一返回 sessionId。请保存创建时的 ID，并用同一 ID 查询认证会话 核验结果。查询接口不返回 customerRedirectURL。

浏览器地址中的参数可能被修改，业务系统应以带鉴权的会话查询结果为准，并按会话 ID 做幂等处理。浏览器关闭、网络中断或平台拒绝无效回调时，客户页面可能收不到跳转；可查询会话结果。