语音对话(/v1/realtime)
呼叫系统把通话中客户一侧的音频实时送上来,智能体用中文普通话回复,回复的文本和语音实时送回;挂机后返回对话记录与意图总结。
入口 wss://api.jftxyun.com:31080/v1/realtime,握手头 Authorization: Bearer <语音对话 key>。key、错误码、费用、查询接口见接入说明。
会话流程
-> session.start 话术、客户信息、音频格式
<- session.ready 会话可用后才能送音频
-> response.create (可选)播开场白,mode=speak_text,不经过模型
-> input_audio.append 客户音频,16 kHz PCM16 单声道,持续发送,AI 说话期间也不停
<- asr.partial / asr.final 客户说的话
<- response.started / response.text.delta / response.text.final AI 回复文本
<- response.audio.start / response.audio.delta / response.audio.done AI 回复语音
<- response.done 本条回复生成结束(不代表已经播完)
<- response.interrupted 客户抢话,这条回复作废,立即清空待播音频
-> session.close 挂机
<- session.result 先 status=processing,再 completed 或 failed
-> session.result.ack 确认已收到结果
<- session.closed
发送的事件
| type | 字段 | 说明 |
|---|---|---|
session.start |
session_id(必填,≤128 字符,建议用呼叫系统的通话 id)audio.input:{"encoding":"pcm_s16le","sample_rate":16000,"channels":1,"frame_ms":20},frame_ms 10–200audio.requested_output:AI 语音格式,sample_rate 取 8000 / 16000 / 24000conversation.prompt_content:话术,≤32768 字conversation.customer:客户信息,原样提供给智能体conversation.history:此前的对话,≤24 轮,[{"role":"user"|"assistant","content":"…"}]conversation.offline_output.fields:会后要返回的结构化字段(出现在 session.result.business_result)features.max_call_seconds:单通时长上限voice.voice_code:本通音色(复刻音色 ID),不填用默认音色
| 首帧,只发一次。超过长度上限的会话直接以 error 结束 |
input_audio.append | session_id、sequence(从 1 起连续)、audio(Base64 PCM) | 按实时节奏持续发送,不要一次性灌入 |
response.create | input: {"mode":"speak_text","text":"…"} | 播报固定文本,如开场白 |
response.cancel | response_id、reason | 主动取消当前回复 |
session.close | reason | 挂机后发送,请求会后结果 |
session.result.ack | result_event_id:completed(或 failed)那条 session.result 的 event_id | 结果保存好后确认 |
收到的事件
| type | 字段 | 说明 |
|---|---|---|
session.ready | 实际的输入、输出音频格式,warnings | 收到后开始送音频 |
asr.partial / asr.final | turn_id、text | 客户这句话的累计文本 / 定稿文本 |
response.started | turn_id、response_id | AI 开始回复客户的这一轮 |
response.text.delta / response.text.final | response_id、text | 回复文本增量 / 全文 |
response.audio.start | response_id、sample_rate、channels、sample_width | 声明后续语音的格式 |
response.audio.delta / response.audio.done | response_id、sequence、audio | 回复语音(Base64 PCM)分块 / 发送结束 |
response.done | response_id | 本条回复的文本和语音都已发完 |
response.interrupted | response_id、reason | 客户抢话:停止播放这条回复并清空缓存,之后到达的同一 response_id 的音频丢弃 |
session.result | status、summary、intention_grade、intention_reason、keywords、tags、turns、turn_count、duration_seconds、business_result(配置了 offline_output.fields 时)、billing | 会后结果,挂机后最多约 90 秒内给出 |
session.closed | reason | 会话结束 |
error | code、fatal、retryable、session_id | 见接入说明的错误码;fatal: true 时会话不能再用 |
转人工与挂机口令
智能体只下发口令,不执行动作。response.text.final 的 text 是下面的固定句时,呼叫系统在这句播完之后执行对应动作:
| 固定句 | 呼叫系统执行 |
|---|---|
| 请稍等,我现在转接值班人员帮您处理 | 转人工 |
| 再见,祝您生活愉快 | 挂机 |
示例代码(Python)
用一段 wav 当作客户说的话:播开场白 → 按实时节奏送音频 → 打印双方文本 → 把 AI 语音存成 wav → 取会后结果。依赖 Python 3.10+ 与 websockets>=14。
pip install "websockets>=14"
export PAA_API_KEY=sk_live_... # 语音对话的 key
python3 realtime_api_sample.py user.wav --out agent.wav
加载中…