POST/api/global-chatbot/demo/voice-speak

将文本转换为语音(文本转语音),用于演示页面的语音输出(如已启用)。

`POST /api/global-chatbot/demo/voice-speak` 将文本转换为语音(前提是演示中的语音功能已启用)。此端点由公共演示页面使用,并非作为可自由使用的通用文本转语音 API 提供。无需仪表板身份验证,而是采用固定的源验证 `https://zentor-app.de` 和 `https://www.zentor-app.de`. 请求包含待输出的文本以及文档化方案中规定的语音选项。客户端应仅发送确实在演示对话中需要朗读的文本。空输入、无效格式或未启用的语音功能必须作为错误处理。本地修改源或从外部域发起调用无法绕过服务器端验证。 该操作会生成音频,因此不能视为幂等的纯读取操作。重复发送相同文本可能会触发多次处理过程。演示界面应在处理期间禁用输出按钮,并在启动新播放前干净地结束当前播放。 合理的流程始于演示中的机器人回复。用户启用语音输出,页面将回复文本发送至 `voice-speak`,接收音频数据或文档化的音频响应,并在浏览器中播放。若因源不被允许导致请求失败,界面不得调用任意替代服务,而应显示语音功能不可用。 密码、令牌或机密内容不得包含在请求中。演示通道是公开的,不用于存储机密企业数据。音频响应也不应永久保存在公共日志中。该端点在技术上与 SIP 语音机器人分离。电话功能在每个租户独立的隔离 SIP 实例中运行,且仅由主管理员激活;`voice-speak` 不控制电话号码,也不启动电话呼叫。 为提升无障碍体验,演示应在音频输出旁始终显示完整文本。语音输出不得包含任何视觉上缺失的信息。浏览器可能在未发生用户交互时阻止播放;因此,启动应通过点击明确触发。必须能够控制中止和重新播放。

身份验证与安全

无需身份验证

Origin 检查固定为 https://zentor-app.de / https://www.zentor-app.de(不可配置,在演示路径上替代小部件令牌)。

幂等: 是

参数

visitor_id(body, string,必填)— 必须为有效的 UUID
text(body, string,必填)— 要转换为语音的文本

响应示例

{"ok":false,"error":{"code":"VOICE_UNAVAILABLE","message":"Sprachfunktion aktuell nicht verfügbar."}}

错误代码

400 INVALID_VISITOR_ID — visitor_id 缺失或不是有效的 UUID。
403 ORIGIN_DENIED — 请求源不是 zentor-app.de。
503 VOICE_UNAVAILABLE — 语音功能当前不可用。

实时测试证明

失败场景(400 INVALID_VISITOR_ID、503 VOICE_UNAVAILABLE,均带有正确的 Origin 标头)已实时验证。同一路径也存在 GET 变体(原生 <audio src> 流式传输,行为相同)。此为 widget.voice_speak 的演示对应项。

← 演示聊天机器人和单点登录