DHCS OPEN API

数字人客服对外接口

本文档仅包含对外业务系统必须使用的 API。保留原 10 个业务接口,增加会话事件、凭证签发、撤销及压力提示接口。管理后台、任务调度和运维接口不在公开范围内。

AI 执行服务:固定话术及公共视频直连可灵,配音沿用数字人上传声纹的已批准克隆配置,使用阿里云百炼 TTS,与动态参数视频保持一致;动态参数视频使用本地或扩展节点合成。回答 ASR 优先本地 FunASR,不可用时直接兜底百炼;人脸和张口沿用本地检测及百炼兜底。原元核 OpenAPI 路由和供应商配置已移除,业务接口字段及鉴权方式不变。

基础地址
https://dhcs-ai.yuancore.com
鉴权方式
Authorization: Bearer <SK>
JSON 编码
application/json; charset=UTF-8
接口数量
14 个外部 API

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。

A

鉴权与通用约定

SK 由管理后台按租户发放,服务端按租户及 API 用户隔离数据。

请求头必传类型示例说明
Authorization必传StringBearer sk_xxxBearer 与 SK 之间保留一个空格。所有公开 API 及返回的媒体地址都需要该请求头。
Content-Type必传Stringapplication/jsonJSON 接口使用该值;上传文件的接口使用 multipart/form-data。
Accept非必传Stringapplication/json建议 JSON 接口传入。
租户参数所有接口都必须传 tenantCode,且必须与 Bearer SK 绑定的租户编码一致。该字段用于明确请求归属,不能用于切换租户。
安全要求不要把 SK 放入 URL、请求体或业务日志。SK 无效、停用或过期后接口返回 401,调用方应停止重试并联系管理员。
跨域/api/** 接受任意网页来源的无 Cookie 跨域请求,包括带 Authorization 的预检请求;跨域许可不替代 SK 或会话 token 鉴权。/admin/api/** 不开放跨域,OSS 视频下载的跨域规则由 OSS 单独配置。

通用返回字段

字段出现条件类型说明
code固定返回Integer业务状态码,成功为 200。
msg固定返回String结果说明或错误原因。
其他字段按接口返回Any当前服务部分接口把业务字段直接放在根对象中,不统一包裹在 data 中。
01POST/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问答节点的参考回答或回答提示。
完整请求 JSON
{
  "tenantCode": "XHRS",
  "scriptName": "保单贷款确认话术",
  "scriptVersion": "1.0",
  "scriptCharacter": "星海客服小元",
  "scriptNodes": [
    {
      "nodeName": "贷款信息确认",
      "nodeType": "问答",
      "nodeContent": "本次贷款金额${贷款金额}元,请问是否确认?",
      "answerGuidance": "确认"
    },
    {
      "nodeName": "结束语",
      "nodeType": "普通",
      "nodeContent": "感谢您的配合,本次服务已完成。"
    }
  ]
}
完整成功返回 JSON
{
  "code": 200,
  "msg": "操作成功"
}
02POST/api/script/query

查询话术

查询指定话术版本的当前处理状态。

请求字段

字段必传类型说明
tenantCode必传String租户编码,必须与当前 SK 绑定的租户一致。
scriptName必传String话术名称。
scriptVersion必传String话术版本。

返回字段

字段出现条件类型说明
state成功时返回String常用值:新创建、视频生成中、准备就绪,异常时可能带 -异常 后缀。
完整请求 JSON
{
  "tenantCode": "XHRS",
  "scriptName": "保单贷款确认话术",
  "scriptVersion": "1.0"
}
完整成功返回 JSON
{
  "code": 200,
  "msg": "操作成功",
  "state": "准备就绪"
}
03POST/api/script/generateNodeVideos

生成话术节点视频

取得指定节点的播报视频。固定文本复用已生成媒体,参数文本按本次参数生成。

请求字段

字段路径必传类型说明
tenantCode必传String租户编码,必须与当前 SK 绑定的租户一致。
scriptName必传String话术名称。
scriptVersion必传String话术版本。
nodeName必传String节点名称,必须存在于已保存的话术中。
scriptParam必传Object参数名与参数值的键值对;节点没有动态参数时传空对象 {}。
scriptParam.*按节点必传String必须覆盖节点文本中使用的全部 ${参数名}。

返回字段

字段出现条件类型说明
videos成功时返回Array<String>按节点文本顺序返回完整 OSS HTTPS 签名 URL,H5 可直接播放;动态参数视频地址有效期为 60 分钟。
完整请求 JSON
{
  "tenantCode": "XHRS",
  "scriptName": "保单贷款确认话术",
  "scriptVersion": "1.0",
  "nodeName": "贷款信息确认",
  "scriptParam": {
    "贷款金额": "32800"
  }
}
完整成功返回 JSON
{
  "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=..."
  ]
}
04POST/api/script/regenerateNodeVideos

重新生成话术节点视频

把指定节点的固定话术媒体重新加入生成队列。动态参数媒体不在该接口中重建。

请求字段

字段必传类型说明
tenantCode必传String租户编码,必须与当前 SK 绑定的租户一致。
scriptName必传String话术名称。
scriptVersion必传String话术版本。
nodeName必传String需要重新生成的节点名称。
异步处理返回 200 表示已受理,不表示视频已完成。随后调用“查询话术”,直到 state 为 准备就绪。
完整请求 JSON
{
  "tenantCode": "XHRS",
  "scriptName": "保单贷款确认话术",
  "scriptVersion": "1.0",
  "nodeName": "贷款信息确认"
}
完整受理返回 JSON
{
  "code": 200,
  "msg": "操作成功"
}
05POST/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。

Base64 字段示例(替换完整请求中的原字段)
{
  "applicantFaceImage": "data:image/jpeg;base64,/9j/(替换为完整JPEG的Base64,不包含此说明)",
  "insuredFaceImage": "iVBORw0KGgo(替换为完整PNG的Base64,不包含此说明)"
}

返回字段

字段路径出现条件类型说明
sessionId成功时返回String会话号。
sessionToken成功时返回String仅授权本次会话的短期 Bearer 凭证。数据库仅存摘要,可跨服务实例校验。
expiresAt成功时返回StringISO 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 的映射,与预下载接口相同。
完整请求 JSON
{
  "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": "结束语"}
  ]
}
完整成功返回 JSON
{
  "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 及其他检测项不变;取消请求不保证上游立即停止计算或免计费。

06POST/api/session/check-answer

检查回答

上传客户单次回答的 WebM 文件,执行转码、ASR、回答判断及配置的检测项。

白名单短回答在精确匹配前忽略句尾“啊、呢、呀、呐”,例如“清楚啊”按“清楚”匹配,“不清楚啊/呢”按“不清楚”匹配,直接走本地规则;“吗、吧”等疑问或不确定表达保留。去除语气词只用于精确匹配,不扩展近音匹配范围。即使由语义模型返回“结束”,原始回答去除句尾语气词后精确命中配置的否定词,也可进入结束动作,不依赖模型返回 answerKeyword。asr 返回匹配后的文本,_asr 及内部识别证据保留原始转写和时间戳;最终动作仍综合配置的其他检测项。

multipart/form-data 字段

字段必传类型说明
tenantCode必传String租户编码,必须与当前 SK 绑定的租户一致。
file必传File / Stringmultipart二进制文件,或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成功时返回StringASR 原始识别文本。
完整调用示例
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'
URL方式完整JSON调用示例
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上传在后台完成;成功返回不代表全部证据已上传。待归档期间历史回放素材可能暂不可用,上传失败保留本地文件并重试,不要因此重复提交回答。请求、返回字段不变。该优化默认关闭,须经部署验收后启用。

完整成功返回 JSON
{
  "code": 200,
  "msg": "操作成功",
  "action": "通过",
  "videos": [],
  "asr": "确认",
  "_asr": "确认"
}
07POST/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成功时返回StringCOMPLETED 表示整段转写及全局检查已完成,不代表所有检测项通过;仍需检查 checkPoints[].passed。
report.global.provider成功时返回StringBAILIAN。
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。整段音频下载和鉴权规则保持不变。

完整 multipart 调用示例
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,不生成成功报告。使用同一会话和完全相同的音频字节重试可复用已有转写任务;上游提交状态不明时不会自动重复提交。该接口等待整段检查结果,不是即时回答接口,调用方需设置足够的请求超时。

完整成功返回 JSON
{
  "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秒不是整个接口的超时,实际检测和媒体处理耗时另计。

08POST/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'
URL方式完整JSON调用示例
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须在本次调用下载完成前有效。

完整成功返回 JSON
{
  "code": 200,
  "msg": "操作成功",
  "headCount": 1,
  "hasApplicantFace": true,
  "hasInsuredFace": true
}
09POST/api/session/mark-ai-fail

AI 误判标记

记录指定会话的 AI 误判反馈,供后续审计与模型问题排查。

请求字段

字段必传类型说明
tenantCode必传String租户编码,必须与当前 SK 绑定的租户一致。
sessionId必传String需要标记的会话号,必须属于当前 SK。
完整请求 JSON
{
  "tenantCode": "XHRS",
  "sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A"
}
完整成功返回 JSON
{
  "code": 200,
  "msg": "操作成功"
}
10POST/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.*有媒体时返回StringOSS HTTPS 签名下载地址,文件版本不变时保持不变,2037-12-31 23:59:59 UTC 到期;链接持有者可直接下载,请勿对外分享。
完整请求 JSON
{
  "tenantCode": "XHRS",
  "scriptName": "保单贷款确认话术",
  "scriptVersion": "1.0"
}
完整成功返回 JSON
{
  "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 确认。生成质检报告不等于正常完成会话。

字段类型必传说明
tenantCodeString是与凭证所属租户一致。
sessionIdString是token 仅可访问绑定会话。
eventIdString是1–128 位字母、数字、下划线、连字符;同一次事件重试必须复用,相同 ID 不可改类型或原因。
eventTypeString是START 开始;HEARTBEAT 心跳;COMPLETE 完整结束;CANCEL 主动退出;TERMINATE 业务终止;ERROR 异常结束。
reasonString否1–64 位大写字母、数字、下划线,例如 USER_EXIT、FLOW_FINISHED;结束时未传则采用事件类型。
occurredAtString通常否,超时补报必传服务端 SK 可补报 ISO 8601 真实结束时间,须在会话开始后及最近 24 小时内;H5 时间不作为统计依据。

START 后建议每 30 秒发送一次心跳;默认超过 120 秒无心跳记为 TIMED_OUT,不计为完整会话。主动退出需主动上报;关闭页面未能成功上报时只能记录超时,不能推断用户真实退出原因。

完整请求 JSON(业务服务端)
{
  "tenantCode": "XHRS",
  "sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A",
  "eventId": "complete-001",
  "eventType": "COMPLETE",
  "reason": "FLOW_FINISHED",
  "occurredAt": "2026-09-21T12:05:00Z"
}
完整成功返回 JSON
{
  "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;结束会话不能继续签发。撤销依赖数据库版本校验,对所有实例立即生效;网络中的已开始请求不能追溯取消。

两接口共用字段类型必传说明
tenantCodeString是SK 所属租户编码。
sessionIdString是该 SK 创建的会话。
完整请求 JSON(两接口相同)
{
  "tenantCode": "XHRS",
  "sessionId": "01KQ4X9G7E4M2R6N8T1W3Y5Z0A"
}
签发完整成功返回 JSON
{
  "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。

撤销完整成功返回 JSON
{"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。该值仅供创建会话前参考,不预留名额、不阻止创建或回答请求,也不保证之后的并发数或响应耗时。

E

错误处理

同时检查 HTTP 状态和返回 JSON 中的 code。

code含义调用方处理
200成功读取接口业务字段。
400参数错误按 msg 修正参数,不要原样重试。
401API 用户或 SK 无效停止调用并检查 SK。
403会话、话术或数字人不属于当前调用方检查 SK 与数据归属。
404话术或会话不存在核对业务标识。
500处理失败记录接口、时间、会话号后联系平台排查。
SK 无效
{
  "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。