DHCS OPEN API
数字人客服对外接口
本文档仅包含对外业务系统必须使用的 API。保留原 10 个业务接口,增加会话事件、凭证签发、撤销及压力提示接口。管理后台、任务调度和运维接口不在公开范围内。
AI 执行服务:固定话术及公共视频直连可灵,配音沿用数字人上传声纹的已批准克隆配置,使用阿里云百炼 TTS,与动态参数视频保持一致;动态参数视频使用本地或扩展节点合成。回答 ASR 优先本地 FunASR,不可用时直接兜底百炼;人脸和张口沿用本地检测及百炼兜底。原元核 OpenAPI 路由和供应商配置已移除,业务接口字段及鉴权方式不变。
SK 只由业务服务端保存。H5 在创建会话后使用返回的 sessionToken,通过 Authorization: Bearer <sessionToken> 访问该会话的检查回答、检查人脸及会话事件;不得把 SK 下发到浏览器。token 不放 Cookie、URL 或 JSON 参数中。会话创建前的查询、预加载由业务服务端使用 SK 完成。
会话 token 默认 60 分钟有效,过期时间以 expiresAt 为准,建议仅保存在 H5 内存中;刷新页面后由业务服务端重新签发。返回给 H5 的视频地址是完整 OSS HTTPS 签名 URL,可直接播放,不需向 OSS 附带 SK 或 sessionToken。固定及公共视频使用可预下载的稳定地址;动态参数视频地址有效期为 60 分钟,过期后需重新获取。签名 URL 持有者可直接下载,请勿对外分享;跨域 H5 若用 fetch 读取视频内容,还需 OSS 配置允许该来源的 CORS。
鉴权与通用约定
SK 由管理后台按租户发放,服务端按租户及 API 用户隔离数据。
| 请求头 | 必传 | 类型 | 示例 | 说明 |
|---|---|---|---|---|
Authorization | 必传 | String | Bearer sk_xxx | Bearer 与 SK 之间保留一个空格。所有公开 API 及返回的媒体地址都需要该请求头。 |
Content-Type | 必传 | String | application/json | JSON 接口使用该值;上传文件的接口使用 multipart/form-data。 |
Accept | 非必传 | String | application/json | 建议 JSON 接口传入。 |
tenantCode,且必须与 Bearer SK 绑定的租户编码一致。该字段用于明确请求归属,不能用于切换租户。/api/** 接受任意网页来源的无 Cookie 跨域请求,包括带 Authorization 的预检请求;跨域许可不替代 SK 或会话 token 鉴权。/admin/api/** 不开放跨域,OSS 视频下载的跨域规则由 OSS 单独配置。通用返回字段
| 字段 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
code | 固定返回 | Integer | 业务状态码,成功为 200。 |
msg | 固定返回 | String | 结果说明或错误原因。 |
| 其他字段 | 按接口返回 | Any | 当前服务部分接口把业务字段直接放在根对象中,不统一包裹在 data 中。 |
/api/script/save保存话术
发布当前租户的话术版本。相同租户、话术名称和版本视为同一条记录;相同内容重试幂等,修改内容或数字人必须提交新的版本。草稿编辑由调用方业务系统管理。
请求字段
| 字段路径 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
scriptName | 必传 | String | 话术名称。 |
scriptVersion | 必传 | String | 话术版本,非空、最多64个字符,例如 1.0 或 20261016162832-0F3MMK。原样保留,不截断;超过限制返回业务 code=400、msg=scriptVersion不能超过64个字符。 |
scriptCharacter | 必传 | String | 数字人中文名称,必须属于当前 SK 所属租户。 |
scriptNodes | 必传 | Array<Object> | 话术节点,至少包含一个节点。 |
scriptNodes[].nodeName | 必传 | String | 节点名称,在同一话术内应保持唯一。 |
scriptNodes[].nodeType | 必传 | String | 节点类型,例如 普通、问答。 |
scriptNodes[].nodeContent | 必传 | String | 数字人播报文本,动态字段写成 ${参数名}。 |
scriptNodes[].answerGuidance | 非必传 | String | 问答节点的参考回答或回答提示。 |
{
"tenantCode": "XHRS",
"scriptName": "保单贷款确认话术",
"scriptVersion": "1.0",
"scriptCharacter": "星海客服小元",
"scriptNodes": [
{
"nodeName": "贷款信息确认",
"nodeType": "问答",
"nodeContent": "本次贷款金额${贷款金额}元,请问是否确认?",
"answerGuidance": "确认"
},
{
"nodeName": "结束语",
"nodeType": "普通",
"nodeContent": "感谢您的配合,本次服务已完成。"
}
]
}{
"code": 200,
"msg": "操作成功"
}/api/script/query查询话术
查询指定话术版本的当前处理状态。
请求字段
| 字段 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
scriptName | 必传 | String | 话术名称。 |
scriptVersion | 必传 | String | 话术版本。 |
返回字段
| 字段 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
state | 成功时返回 | String | 常用值:新创建、视频生成中、准备就绪,异常时可能带 -异常 后缀。 |
{
"tenantCode": "XHRS",
"scriptName": "保单贷款确认话术",
"scriptVersion": "1.0"
}{
"code": 200,
"msg": "操作成功",
"state": "准备就绪"
}/api/script/generateNodeVideos生成话术节点视频
取得指定节点的播报视频。固定文本复用已生成媒体,参数文本按本次参数生成。
请求字段
| 字段路径 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
scriptName | 必传 | String | 话术名称。 |
scriptVersion | 必传 | String | 话术版本。 |
nodeName | 必传 | String | 节点名称,必须存在于已保存的话术中。 |
scriptParam | 必传 | Object | 参数名与参数值的键值对;节点没有动态参数时传空对象 {}。 |
scriptParam.* | 按节点必传 | String | 必须覆盖节点文本中使用的全部 ${参数名}。 |
返回字段
| 字段 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
videos | 成功时返回 | Array<String> | 按节点文本顺序返回完整 OSS HTTPS 签名 URL,H5 可直接播放;动态参数视频地址有效期为 60 分钟。 |
{
"tenantCode": "XHRS",
"scriptName": "保单贷款确认话术",
"scriptVersion": "1.0",
"nodeName": "贷款信息确认",
"scriptParam": {
"贷款金额": "32800"
}
}{
"code": 200,
"msg": "操作成功",
"videos": [
"https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/script/loan-prefix.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/param/loan-32800.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/script/confirm.mp4?Expires=...&OSSAccessKeyId=...&Signature=..."
]
}/api/script/regenerateNodeVideos重新生成话术节点视频
把指定节点的固定话术媒体重新加入生成队列。动态参数媒体不在该接口中重建。
请求字段
| 字段 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
scriptName | 必传 | String | 话术名称。 |
scriptVersion | 必传 | String | 话术版本。 |
nodeName | 必传 | String | 需要重新生成的节点名称。 |
state 为 准备就绪。{
"tenantCode": "XHRS",
"scriptName": "保单贷款确认话术",
"scriptVersion": "1.0",
"nodeName": "贷款信息确认"
}{
"code": 200,
"msg": "操作成功"
}/api/session/create创建会话
创建一次数字人双录会话,并返回补全媒体地址后的执行流程。
请求字段
| 字段路径 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
sessionId | 必传 | String | 调用方生成的全局唯一会话号,重试时不得换号;1–128 位,仅支持字母、数字、下划线和短横线。 |
scriptName | 必传 | String | 已准备就绪的话术名称。 |
scriptVersion | 必传 | String | 话术版本,非空、最多64个字符,与保存话术时完全一致。超过限制返回业务 code=400、msg=scriptVersion不能超过64个字符,在归档照片或创建会话前拒绝。 |
applicantFaceImage | 必传 | String | 属性名不变,兼容 HTTP/HTTPS 公网直链、当前租户 customer 目录的 s3:// 地址、标准纯 Base64,或 data:image/jpeg;base64,... / data:image/png;base64,...。服务端校验后按图片内容归档到当前租户。JPEG/PNG,解码后最大20MB、1600万像素;Base64 不含换行,Data URI 声明须与实际图片类型一致。URL可带有效签名,不支持跳转、内网地址或额外请求头认证。 |
insuredFaceImage | 选填 | String | 属性名不变,图片格式与 applicantFaceImage 相同,各字段可独立使用 URL、s3:// 或 Base64。不同人时可不传,未传则不做被保人人脸身份比对,不因缺照片判失败;传了则正常比对。同一人时未传自动复用投保人照片。投保人照片仍必传。重复创建时图片字节内容须保持不变,URL须仍有效。 |
scriptParam | 必传 | Object | 话术动态参数;没有动态参数时传空对象。 |
scriptFlow | 必传 | Array<Object> | 本次会话实际执行的节点列表。 |
scriptFlow[].nodeIndex | 必传 | Integer | 节点顺序,从 0 开始。 |
scriptFlow[].nodeName | 必传 | String | 节点名称,必须存在于话术定义中。 |
scriptFlow[].checkPoints | 非必传 | Array<Object> | 该节点要执行的检测项;普通播报节点可省略。 |
checkPoints[].checkPointName | 有检测项时必传 | String | 例如人脸对比检测、肯定答复检测、代答检测、敏感词检测、诱导答复检测。 |
checkPoints[].checkTarget | 按检测项必传 | String | 人脸检测传投保人/被保人;敏感词检测传竖线分隔的词语。 |
Base64 仍放在上述原字段中,不新增 applicantFaceImageBase64 等属性。相同图片字节的 URL、纯 Base64 和 Data URI 使用相同归档引用,保持创建幂等;原始 Base64 不写入接口日志。Base64 体积约为原文件的 4/3,整个 JSON 还须符合网关请求体总大小限制;照片较大时建议压缩后传入,或沿用公网 URL。
{
"applicantFaceImage": "data:image/jpeg;base64,/9j/(替换为完整JPEG的Base64,不包含此说明)",
"insuredFaceImage": "iVBORw0KGgo(替换为完整PNG的Base64,不包含此说明)"
}返回字段
| 字段路径 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
sessionId | 成功时返回 | String | 会话号。 |
sessionToken | 成功时返回 | String | 仅授权本次会话的短期 Bearer 凭证。数据库仅存摘要,可跨服务实例校验。 |
expiresAt | 成功时返回 | String | ISO 8601 UTC 过期时间,例如 2026-09-21T12:30:00Z。 |
scriptFlow | 成功时返回 | Array<Object> | 服务端补全后的会话流程。 |
scriptFlow[].nodeType | 成功时返回 | String | 节点类型。 |
scriptFlow[].nodeSubtitle | 成功时返回 | String | 动态参数替换后的完整字幕。 |
scriptFlow[].nodeVideos | 成功时返回 | Array<String> | 完整 OSS HTTPS 签名 URL;动态参数视频地址有效期为 60 分钟。 |
scriptFlow[].answerGuidance | 问答节点返回 | String | 回答提示。 |
scriptFlow[].answerGuidanceVideo | 问答节点返回 | String | 完整 OSS HTTPS 签名 URL。 |
commonVideo | 成功时返回 | Object | 公共媒体名称到完整 OSS HTTPS URL 的映射,与预下载接口相同。 |
{
"tenantCode": "XHRS",
"sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A",
"scriptName": "保单贷款确认话术",
"scriptVersion": "1.0",
"applicantFaceImage": "https://files.example.com/01KQ4X/applicant.jpg",
"insuredFaceImage": "https://files.example.com/01KQ4X/applicant.jpg",
"scriptParam": {
"贷款金额": "32800",
"是否同一人": "是"
},
"scriptFlow": [
{
"nodeIndex": 0,
"nodeName": "贷款信息确认",
"checkPoints": [
{"checkPointName": "人脸对比检测", "checkTarget": "投保人"},
{"checkPointName": "肯定答复检测"},
{"checkPointName": "代答检测"}
]
},
{"nodeIndex": 1, "nodeName": "结束语"}
]
}{
"code": 200,
"msg": "操作成功",
"sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A",
"sessionToken": "st_EXAMPLE_ONLY_NOT_A_REAL_TOKEN",
"expiresAt": "2026-09-21T12:30:00Z",
"scriptFlow": [
{
"nodeIndex": 0,
"nodeName": "贷款信息确认",
"nodeType": "问答",
"nodeSubtitle": "本次贷款金额32800元,请问是否确认?",
"nodeVideos": [
"https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/script/loan-prefix.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/param/loan-32800.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/script/confirm.mp4?Expires=...&OSSAccessKeyId=...&Signature=..."
],
"answerGuidance": "确认",
"answerGuidanceVideo": "https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/script/answer-confirm.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"checkPoints": [
{"checkPointName": "人脸对比检测", "checkTarget": "投保人"},
{"checkPointName": "肯定答复检测"},
{"checkPointName": "代答检测"}
]
},
{
"nodeIndex": 1,
"nodeName": "结束语",
"nodeType": "普通",
"nodeSubtitle": "感谢您的配合,本次服务已完成。",
"nodeVideos": ["https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/script/finish.mp4?Expires=...&OSSAccessKeyId=...&Signature=..."]
}
],
"commonVideo": {
"等待": "https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/digital-human/XHRS/DH_1/v2/waiting.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"请您回答": "https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/common/please-answer.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"画外音检测提示": "https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/common/offscreen-warning.mp4?Expires=...&OSSAccessKeyId=...&Signature=..."
}
}需要语义判断时,同时请求 deepseek-flash 与 qwen3.8-27b,采用最先返回且通过格式校验的结果,并取消另一路。一方报错或返回无效内容时继续等待另一方;两方均失败或超过 5 秒等待期限时沿用现有失败处理,不默认通过。两模型均关闭思考模式,分别使用各自提示词。本地快速匹配、ASR 及其他检测项不变;取消请求不保证上游立即停止计算或免计费。
/api/session/check-answer检查回答
上传客户单次回答的 WebM 文件,执行转码、ASR、回答判断及配置的检测项。
白名单短回答在精确匹配前忽略句尾“啊、呢、呀、呐”,例如“清楚啊”按“清楚”匹配,“不清楚啊/呢”按“不清楚”匹配,直接走本地规则;“吗、吧”等疑问或不确定表达保留。去除语气词只用于精确匹配,不扩展近音匹配范围。即使由语义模型返回“结束”,原始回答去除句尾语气词后精确命中配置的否定词,也可进入结束动作,不依赖模型返回 answerKeyword。asr 返回匹配后的文本,_asr 及内部识别证据保留原始转写和时间戳;最终动作仍综合配置的其他检测项。
multipart/form-data 字段
| 字段 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
file | 必传 | File / String | multipart二进制文件,或JSON/表单中的 HTTP/HTTPS URL 字符串,二选一,字段名不变。URL需为公网直链,WebM/MP4,最大20MB,不跟随跳转,不携带调用方认证头下载。 |
sessionId | 必传 | String | 创建会话时使用的会话号;1–128 位,仅支持字母、数字、下划线和短横线。 |
nodeName | 必传 | String | 当前问答节点名称。 |
video | 必传 | String | 本次回答片段唯一标识,1–128 位,仅支持字母、数字、下划线和短横线,例如 answer-0-1;后续报告继续使用该值。 |
返回字段
| 字段 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
action | 成功时返回 | String | 通过、播放 或 结束。 |
videos | 成功时返回 | Array<String> | 需要追加播放的提示媒体;无需播放时为空数组。 |
asr | 成功时返回 | String | 修正后的识别文本。 |
_asr | 成功时返回 | String | ASR 原始识别文本。 |
curl -sS -X POST 'https://dhcs-ai.yuancore.com/api/session/check-answer' \
-H 'Authorization: Bearer <SK>' \
-F 'tenantCode=XHRS' \
-F 'file=@answer-0-1.webm;type=video/webm' \
-F 'sessionId=01KQ4X9G7E4M2R6N8T1W3Y5Z0A' \
-F 'nodeName=贷款信息确认' \
-F 'video=answer-0-1'curl -sS -X POST 'https://dhcs-ai.yuancore.com/api/session/check-answer' \
-H 'Authorization: Bearer <SK>' -H 'Content-Type: application/json' \
-d '{"tenantCode":"XHRS","sessionId":"01KQ4X9G7E4M2R6N8T1W3Y5Z0A","nodeName":"贷款信息确认","video":"answer-0-1","file":"https://files.example.com/answer-0-1.webm"}'表单URL方式:保留上方所有 -F 参数,将文件字段换成 --form-string 'file=https://files.example.com/answer-0-1.webm';也支持 application/x-www-form-urlencoded。不得同时传文件和URL,不得重复传同名参数。下载失败或地址、格式不合法返回业务码400;下载单次最长60秒。
启用回答链路优化时,媒体可靠落盘、检测结果及归档任务持久化后即可返回,S3上传在后台完成;成功返回不代表全部证据已上传。待归档期间历史回放素材可能暂不可用,上传失败保留本地文件并重试,不要因此重复提交回答。请求、返回字段不变。该优化默认关闭,须经部署验收后启用。
{
"code": 200,
"msg": "操作成功",
"action": "通过",
"videos": [],
"asr": "确认",
"_asr": "确认"
}/api/session/report生成质检报告
以 multipart/form-data 提交完整播放记录及整段 session.mp3。音频归档后直接由百炼转写,用于全局敏感词和违规引导话术检查;不占用本地短回答 ASR 队列。
multipart/form-data 字段
| 字段路径 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
sessionId | 必传 | String | 会话号。 |
risk | 必传 | String | 前端汇总风险,传 低、中 或 高。 |
audioFile | 必传 | File | 整段会话 session.mp3,包含客户与数字人的完整混合声音(包括回答之外的声音),不能仅拼接回答片段。单声道 MP3,最大20MB、60分钟;推荐16kHz。文件内容会校验,不支持URL替代。 |
playRecords | 必传 | String(JSON 数组) | 各话术节点的播放记录,表单内传序列化后的 JSON 数组,最大1000000个字符。以下子字段属于该数组,不是独立表单字段。 |
playRecords[].nodeName | 必传 | String | 节点名称。 |
playRecords[].videoRecords | 必传 | Array<Object> | 该节点按播放顺序记录的媒体片段。 |
videoRecords[].start | 必传 | Integer | 相对会话开始时间的毫秒数。 |
videoRecords[].end | 必传 | Integer | 相对会话开始时间的结束毫秒数。 |
videoRecords[].video | 必传 | String | 系统媒体传播放 URL,客户回答传检查回答时的 answer-* 标识。 |
log | 非必传 | String | 调用端会话日志;仅在协查时建议传入。 |
返回字段
| 字段路径 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
checkResult | 成功时返回 | String | 最终结论:低风险、中风险 或 高风险。整段ASR全局检查中,敏感词检测或诱导答复检测(违规引导)任一项 passed=0,最终为高风险,不受客户端低、中风险限制;未命中不降低客户端原有风险。命中明细和原始ASR保留,旧报告不会自动重算。 |
asr | 成功时返回 | Array<Object> | 按节点汇总的识别结果。 |
asr[].nodeName | 固定返回 | String | 节点名称。 |
asr[].nodeContent | 固定返回 | String | 节点播报字幕。 |
asr[].start | 固定返回 | Integer | 节点转写区间开始毫秒数;首节点从0开始,与对应 report.nodes 一致。 |
asr[].end | 固定返回 | Integer | 下一节点最早播放开始毫秒数;末节点到 audioDurationMs,与对应 report.nodes 一致。 |
asr[].asrText | 固定返回 | String | 同一份整段转写按节点时间切片,保留插话、重答、重复播报及原始标点;无语音为空字符串。不再拼接预设话术或单次回答,nodeContent 仍为标准话术,不额外调用ASR。 |
report.global | 成功时返回 | Object | 全局检测结果。 |
report.global.status | 成功时返回 | String | COMPLETED 表示整段转写及全局检查已完成,不代表所有检测项通过;仍需检查 checkPoints[].passed。 |
report.global.provider | 成功时返回 | String | BAILIAN。 |
report.global.audioFile | 成功时返回 | String | 业务域名中转音频地址:https://dhcs-ai.yuancore.com/media/session-reports/{sessionId}/audio。GET 下载携带所属调用方 SK,或使用已登录的管理员会话。 |
report.global.audioSha256 | 成功时返回 | String | 原始上传音频的 SHA-256,用于证据核验。 |
report.global.audioDurationMs | 成功时返回 | Integer | 整段音频时长,毫秒。 |
report.global.asr | 成功时返回 | Object | 真实整段转写结果:data 为完整文本,timestamps 为毫秒时间对的JSON字符串,words 为词级文本、时间和字符位置。顶层 asr 从该结果按节点时间切分;全局原始文本、检查结果和命中时间不改写。 |
report.nodes | 成功时返回 | Array<Object> | 逐节点检测结果。 |
report.nodes[].checkPoints | 固定返回 | Array<Object> | 检测项结果,passed 为 1 表示通过、0 表示不通过。 |
词开始时间必须按文本顺序不倒退,且严格小于实际录音时长;词结束时间仅允许超出录音尾部最多150毫秒的编码取整误差。超出或时间顺序无效返回503,不钳制或改写原始ASR时间戳。
节点分段采用各节点 videoRecords 最早开始时间确定顺序,不依赖媒体数组顺序;返回节点数组仍保持请求顺序。节点间隙归前一节点,录音开头和尾部分别归首尾节点。词按 begin_time 归属,边界开始的词归后一节点,跨边界词只出现一次并保留其后标点/空白。缺少播放时间、不同节点开始时间重复或开始超出录音范围返回业务400;词级位置或时间戳无效返回503,不退回预设话术拼接。旧报告不会自动重算。
报告检测项不返回 faceImage 或 frames 字段(直接省略,不是空值或空数组,历史记录中的同名字段也不透出)。检查结论、其他检测字段、内部参考照片、关键帧证据及管理端图片查看能力不变;不新增图片 token。整段音频下载和鉴权规则保持不变。
curl -sS -X POST 'https://dhcs-ai.yuancore.com/api/session/report' \
-H 'Authorization: Bearer <SK>' \
--form-string 'tenantCode=XHRS' \
--form-string 'sessionId=01KQ4X9G7E4M2R6N8T1W3Y5Z0A' \
--form-string 'risk=低' \
--form-string 'playRecords=[{"nodeName":"贷款信息确认","videoRecords":[{"start":120,"end":3860,"video":"https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/script/loan-prefix.mp4"},{"start":3940,"end":5180,"video":"answer-0-1"}]}]' \
--form-string 'log=player ready; answer uploaded; report requested' \
-F 'audioFile=@session.mp3;type=audio/mpeg'不要手动设置 Content-Type,curl/HTTP客户端需要自动生成 multipart boundary。旧 application/json 调用不再接受(HTTP 415)。调用方可从已合并的整段视频提取单声道 MP3 后上传,不必让 H5 重录。
缺音频、文件格式/大小/时长不符返回业务 code=400;归档、百炼转写或全局检查未完成返回 code=503,不生成成功报告。使用同一会话和完全相同的音频字节重试可复用已有转写任务;上游提交状态不明时不会自动重复提交。该接口等待整段检查结果,不是即时回答接口,调用方需设置足够的请求超时。
{
"code": 200,
"msg": "操作成功",
"checkResult": "低风险",
"asr": [
{
"nodeName": "贷款信息确认",
"nodeContent": "本次贷款金额32800元,请问是否确认?",
"start": 0,
"end": 5300,
"asrText": "本次贷款金额32800元,请问是否确认?确认"
}
],
"report": {
"global": {
"status": "COMPLETED",
"provider": "BAILIAN",
"audioFile": "https://dhcs-ai.yuancore.com/media/session-reports/01KQ4X9G7E4M2R6N8T1W3Y5Z0A/audio",
"audioSha256": "0000000000000000000000000000000000000000000000000000000000000000",
"audioDurationMs": 5300,
"asr": {
"code": 200,
"provider": "BAILIAN",
"data": "本次贷款金额32800元,请问是否确认?确认",
"timestamps": "[[120,3860],[3940,5180]]",
"words": [
{"text": "本次贷款金额32800元,请问是否确认?", "begin_time": 120, "end_time": 3860, "startOffset": 0, "endOffset": 20},
{"text": "确认", "begin_time": 3940, "end_time": 5180, "startOffset": 20, "endOffset": 22}
]
},
"checkPoints": [
{"checkPointName": "诱导答复检测", "passed": 1, "start": 0},
{"checkPointName": "敏感词检测", "passed": 1, "start": 0}
]
},
"nodes": [
{
"nodeIndex": 0,
"nodeName": "贷款信息确认",
"start": 0,
"end": 5300,
"checkPoints": [
{"checkPointName": "人脸对比检测", "passed": 1},
{"checkPointName": "肯定答复检测", "passed": 1},
{"checkPointName": "代答检测", "passed": 1}
]
}
]
}
}人脸/张口检测繁忙时先排队,各阶段最多等待5秒;图片与视频检测入口独立排队。队满、排队超时或中断不算检测通过,检查人脸及检查回答接口返回业务 code=503、msg、reason(如 FACE_CHECK_QUEUE_TIMEOUT 或 LOCAL_QUEUE_TIMEOUT),HTTP状态仍为200。不得将503当作身份不匹配或通过。5秒不是整个接口的超时,实际检测和媒体处理耗时另计。
/api/session/check-face检查人脸
上传当前画面截图,核对人数以及投保人、被保人是否出镜。
multipart/form-data 字段
| 字段 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
file | 必传 | File / String | 当前画面:multipart二进制文件或JSON/表单中的 HTTP/HTTPS URL,二选一。URL图片支持JPEG/PNG,最大20MB、1600万像素;公网直链且不能跳转,支持URL签名,不支持额外下载认证头。 |
sessionId | 必传 | String | 会话号。 |
nodeName | 必传 | String | 当前节点名称,用于日志定位。 |
headCount | 必传 | Integer | 调用端检测到的人数,用于与服务端结果比对。 |
begin | 非必传 | String | 截图开始时间标识;不传时服务端使用当前时间。 |
返回字段
| 字段 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
headCount | 识别成功时返回 | Integer | 服务端识别到的人数。 |
hasApplicantFace | 识别成功时返回 | Boolean | 是否匹配投保人人脸。 |
hasInsuredFace | 识别成功时返回 | Boolean | 是否匹配被保人人脸;未提供照片时为 false,表示未比对,不代表不通过。 |
insuredIdentityRequested | 识别成功时返回 | Boolean | 是否请求被保人人脸身份比对。false 时跳过被保人身份要求;代答张口检查仍独立执行,不作身份已确认的声明。 |
curl -sS -X POST 'https://dhcs-ai.yuancore.com/api/session/check-face' \
-H 'Authorization: Bearer <SK>' \
-F 'tenantCode=XHRS' \
-F 'file=@check-face.jpg;type=image/jpeg' \
-F 'sessionId=01KQ4X9G7E4M2R6N8T1W3Y5Z0A' \
-F 'nodeName=贷款信息确认' \
-F 'headCount=1' \
-F 'begin=20260921103022125'curl -sS -X POST 'https://dhcs-ai.yuancore.com/api/session/check-face' \
-H 'Authorization: Bearer <SK>' -H 'Content-Type: application/json' \
-d '{"tenantCode":"XHRS","sessionId":"01KQ4X9G7E4M2R6N8T1W3Y5Z0A","nodeName":"贷款信息确认","headCount":1,"begin":"20260921103022125","file":"https://files.example.com/check-face.jpg"}'表单URL方式与检查回答一致:使用 --form-string 'file=https://files.example.com/check-face.jpg' 替换二进制文件字段,其他参数不变。使用sessionToken时按鉴权章节传递;SK或token不会发送到文件下载服务器。所有URL须在本次调用下载完成前有效。
{
"code": 200,
"msg": "操作成功",
"headCount": 1,
"hasApplicantFace": true,
"hasInsuredFace": true
}/api/session/mark-ai-failAI 误判标记
记录指定会话的 AI 误判反馈,供后续审计与模型问题排查。
请求字段
| 字段 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
sessionId | 必传 | String | 需要标记的会话号,必须属于当前 SK。 |
{
"tenantCode": "XHRS",
"sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A"
}{
"code": 200,
"msg": "操作成功"
}/api/script/query-common-videos查询话术公共视频
用于进入会话前预下载数字人的公共提示视频。查询接口仍需租户 SK;返回可直接从 OSS 下载的签名 URL,不经过 302 跳转。文件未变时 URL 保持不变,文件更新后 URL 随之更新;固定到期时间为 2037-12-31 23:59:59 UTC。
请求字段
| 字段 | 必传 | 类型 | 说明 |
|---|---|---|---|
tenantCode | 必传 | String | 租户编码,必须与当前 SK 绑定的租户一致。 |
scriptName | 必传 | String | 话术名称。 |
scriptVersion | 必传 | String | 话术版本,用于确定数字人。 |
返回字段
| 字段 | 出现条件 | 类型 | 说明 |
|---|---|---|---|
commonVideo | 成功时返回 | Object | 媒体名称到媒体地址的映射,键名由当前数字人已配置的公共/知识库媒体决定。 |
commonVideo.* | 有媒体时返回 | String | OSS HTTPS 签名下载地址,文件版本不变时保持不变,2037-12-31 23:59:59 UTC 到期;链接持有者可直接下载,请勿对外分享。 |
{
"tenantCode": "XHRS",
"scriptName": "保单贷款确认话术",
"scriptVersion": "1.0"
}{
"code": 200,
"msg": "操作成功",
"commonVideo": {
"等待": "https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/digital-human/XHRS/DH_1/v2/waiting.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"请您回答": "https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/common/please-answer.mp4?Expires=...&OSSAccessKeyId=...&Signature=...",
"知识库-贷款利率说明": "https://yc-dhcs.oss-cn-hangzhou.aliyuncs.com/video/XHRS/xiaoyuan/knowledge/loan-rate.mp4?Expires=...&OSSAccessKeyId=...&Signature=..."
}
}11 · 会话生命周期
POST /api/session/event,JSON。H5 可上报 START、HEARTBEAT、CANCEL、ERROR;COMPLETE 和 TERMINATE 必须由业务服务端持 SK 确认。生成质检报告不等于正常完成会话。
| 字段 | 类型 | 必传 | 说明 |
|---|---|---|---|
| tenantCode | String | 是 | 与凭证所属租户一致。 |
| sessionId | String | 是 | token 仅可访问绑定会话。 |
| eventId | String | 是 | 1–128 位字母、数字、下划线、连字符;同一次事件重试必须复用,相同 ID 不可改类型或原因。 |
| eventType | String | 是 | START 开始;HEARTBEAT 心跳;COMPLETE 完整结束;CANCEL 主动退出;TERMINATE 业务终止;ERROR 异常结束。 |
| reason | String | 否 | 1–64 位大写字母、数字、下划线,例如 USER_EXIT、FLOW_FINISHED;结束时未传则采用事件类型。 |
| occurredAt | String | 通常否,超时补报必传 | 服务端 SK 可补报 ISO 8601 真实结束时间,须在会话开始后及最近 24 小时内;H5 时间不作为统计依据。 |
START 后建议每 30 秒发送一次心跳;默认超过 120 秒无心跳记为 TIMED_OUT,不计为完整会话。主动退出需主动上报;关闭页面未能成功上报时只能记录超时,不能推断用户真实退出原因。
{
"tenantCode": "XHRS",
"sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A",
"eventId": "complete-001",
"eventType": "COMPLETE",
"reason": "FLOW_FINISHED",
"occurredAt": "2026-09-21T12:05:00Z"
}{
"code": 200,
"msg": "操作成功",
"data": {
"sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A",
"lifecycle": "COMPLETED",
"endReason": "FLOW_FINISHED"
}
}返回字段:code 为整数业务状态码,msg 为说明文本;成功时 data.sessionId 为会话号,data.lifecycle 为 CREATED、ACTIVE、COMPLETED、INTERRUPTED、ERROR、TIMED_OUT 或 EXPIRED,data.endReason 为结束原因字符串,尚未结束时为 null。重复相同事件不重复累计次数,返回当前会话状态。
12–13 · 会话凭证签发和撤销
POST /api/session/token 签发新凭证;POST /api/session/token/revoke 撤销本会话全部已签发凭证。两者均只能由业务服务端持 SK 调用,H5 token 无权限。签发不会撤销旧 token;结束会话不能继续签发。撤销依赖数据库版本校验,对所有实例立即生效;网络中的已开始请求不能追溯取消。
| 两接口共用字段 | 类型 | 必传 | 说明 |
|---|---|---|---|
| tenantCode | String | 是 | SK 所属租户编码。 |
| sessionId | String | 是 | 该 SK 创建的会话。 |
{
"tenantCode": "XHRS",
"sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A"
}{
"code": 200,
"msg": "操作成功",
"data": {
"sessionToken": "st_EXAMPLE_ONLY_NOT_A_REAL_TOKEN",
"expiresAt": "2026-09-21T12:30:00Z"
}
}成功时 data.sessionToken(String,固定返回)为新会话凭证,data.expiresAt(String,固定返回)为 ISO 8601 UTC 过期时间。撤销接口成功只返回 code 和 msg,无 data。
{"code": 200, "msg": "操作成功"}14 · 会话压力提示
服务端启用动态 CPU 调度时,本地回答检查与视频合成共享整机可用算力,优先处理客户回答。线程档位和 CPU 预算由运营监控展示,不需要业务调用方传入参数;该机制不取消外部 AI 服务的并发限制,也不保证所有回答都在固定时间内完成。
POST /api/session/capacity 仅供业务服务端持 SK 调用,H5 的会话 token 无权限。请求 JSON 为 {"tenantCode":"XHRS"};成功返回 {"code":200,"msg":"操作成功","canCreateSession":true}。有心跳正常且底片已就绪的扩展机时(worker 忙碌仍算在线),全平台实时会话少于 30 路返回 true,达到 30 路返回 false。实时会话按 ACTIVE 状态及心跳有效期统计,排除历史回放,包含压测会话;不是仅统计当前租户。没有可用扩展机时保留原规则:正在处理的回答检查请求少于 10 个返回 true。状态查询异常返回 false。该值仅供创建会话前参考,不预留名额、不阻止创建或回答请求,也不保证之后的并发数或响应耗时。
错误处理
同时检查 HTTP 状态和返回 JSON 中的 code。
| code | 含义 | 调用方处理 |
|---|---|---|
200 | 成功 | 读取接口业务字段。 |
400 | 参数错误 | 按 msg 修正参数,不要原样重试。 |
401 | API 用户或 SK 无效 | 停止调用并检查 SK。 |
403 | 会话、话术或数字人不属于当前调用方 | 检查 SK 与数据归属。 |
404 | 话术或会话不存在 | 核对业务标识。 |
500 | 处理失败 | 记录接口、时间、会话号后联系平台排查。 |
{
"code": 401,
"msg": "API用户或SK无效"
}{
"code": 403,
"msg": "会话不属于当前API用户"
}会话问题定位
运营人员可在管理后台「会话记录」按话术节点查看每次回答、人脸检测和最终质检请求,包含上传媒体、ASR、完整业务输入输出及耗时。业务字段及文件签名查询参数不再脱敏,仅保护 SK、密码、会话 token 等认证凭据。历史写入时已隐藏的值无法恢复;超出大小限制或未记录的数据不补造。文件通过关联素材查看,创建接口内联 Base64 图片仍不重复写入 HTTP 审计日志。新记录提供请求关联和阶段时间线;S3 地址是存储位置,实际 AI 服务以检测记录为准。
详情功能仅供登录后的管理员使用。报告文件 GET 下载需携带所属调用方的 Authorization: Bearer <SK>,或使用管理员登录会话;按租户、API 用户及会话校验归属,直接返回文件,不跳转 OSS。清理后返回 HTTP 410。排查时请提供会话 ID、节点名称及响应头 X-Request-Id;不要提交 SK 或会话 token。