本文介绍千问实时语音/音视频翻译 API 的客户端事件,包括事件类型、参数和示例。
相关文档:实时语音/音视频翻译-千问。
说明本页为 Qwen-LiveTranslate-Realtime 的事件参考,事件定义以 WebSocket 接入为基础。AOQ、WebRTC 通过各自的数据通道收发模型事件,媒体通过媒体轨道传输。请先阅读WebSocket 接入、WebRTC 接入或AOQ 接入。
WebSocket SDK 用法参见 Python SDK和 Java SDK。型号与协议选择参见概述。
session.update
客户端建立 WebSocket 连接后,需首先发送该事件,用于更新会话的默认配置。
服务端收到 session.update 事件后,会校验参数。如果参数不合法,则返回错误;如果参数合法,则更新并返回完整的配置。
typestring(必选)事件类型,固定为session.update。
sessionobject(可选)会话配置。
属性
input_modalitiesarray(可选)适用于 WebSocket 接入的 qwen3.8-livetranslate-flash-realtime。可设为 ["audio"](仅音频,默认)或 ["audio", "video"](音频和图片)。包含 video 时,模型才会处理 input_image_buffer.append 发送的图片。
output_modalitiesarray(可选)适用于 qwen3.8-livetranslate-flash-realtime。输出模态,可设置为 ["text"](仅文本)或 ["text", "audio"](文本和音频,默认值)。
audioobject(可选)适用于 qwen3.8-livetranslate-flash-realtime。音频配置。
属性
inputobject输入音频配置。
属性
formatobject(可选)输入音频格式。
属性
typestring(可选)音频格式,可选值为 pcm(默认)和 opus。
sample_rateinteger(可选)输入音频的采样率,单位为 Hz,默认为 16000。
turn_detectionobject(可选)语音检测配置。
属性
typestring(可选)可选值:speaker_detection(默认,开启实时说话人分离)、server_vad(语音活动检测)。
thresholdnumber(可选)检测阈值。使用 speaker_detection 时,用于区分静音和有效人声,低于阈值的声音会被过滤,不输入模型;取值固定为 0.5。
outputobject(可选)译音配置。
属性
voicestring(可选)译音音色。未启用声音复刻时,默认使用 Tina。启用实时声音复刻且 voice_clone_options.frequency 为 once 或 always 时,设为 default。
modalitiesarray(可选)适用于 qwen3.5-livetranslate-flash-realtime。
模型输出模态设置,可选值:
-
["text"]
仅输出文本。
-
["text","audio"](默认值)
输出文本与音频。
voicestring(可选)生成音频的音色。未启用声音复刻时,可设置为系统预设音色,可选值参见支持的音色。qwen3.8-livetranslate-flash-realtime 和 qwen3.5-livetranslate-flash-realtime 的默认音色为 Tina;qwen3-livetranslate-flash-realtime 的默认音色为 Cherry。
3.8 也支持在 audio 对象的 output 中设置音色。
启用声音复刻(
enable_voice_clone为true)时,voice的取值取决于voice_clone_options.frequency:当frequency为once或always时,必须设置为default;当frequency为never时,设置为用户预先复刻的音色 ID。此时不可设置为系统预设音色,否则服务端会返回错误。
enable_voice_cloneboolean(可选)是否启用声音复刻。默认值为false。启用后,可在翻译时实时复刻输入音频的音色,也可使用预先复刻的音色。此时voice不再使用系统预设音色,需设置为default或用户预先通过声音复刻 API复刻的音色 ID。
voice_clone_optionsobject(可选)声音复刻控制参数,仅在enable_voice_clone为true时生效。
属性
frequencystring(可选)音色复刻频率,可选值:
-
never不在服务端进行音色复刻,使用用户预先复刻好的音色。此时
voice需设置为用户的复刻音色 ID。 -
once会话开始时基于输入音频进行一次音色复刻,后续输出复用该音色。适合单人演讲场景。此时
voice需设置为default。 -
always每次输出前基于输入音频进行实时音色复刻,音色跟随输入动态变化。适合多人对话场景。此时
voice需设置为default。
sample_rateinteger(可选)适用于 qwen3.5-livetranslate-flash-realtime。
输入音频的采样率,单位为Hz。可选值:
- 8000
- 16000(默认)
input_audio_transcriptionobject(可选)适用于 qwen3.5-livetranslate-flash-realtime。
qwen3.8-livetranslate-flash-realtime 的 ASR 始终开启,不支持关闭,识别结果免费。
输入音频相关配置。
属性
modelstring|null(可选)语音识别模型,默认值为 qwen3-asr-flash-realtime,ASR 默认启用。服务端会在翻译的同时返回输入音频的语音识别结果(源语言原文),通过conversation.item.input_audio_transcription.text和conversation.item.input_audio_transcription.completed事件返回。如需关闭 ASR,请将此参数显式设置为 null。
可选值:qwen3-asr-flash-realtime(默认,启用 ASR)、null(关闭 ASR)。
languagestring(可选)翻译源语种,可选值:支持的语种。默认不填写,此时模型会自动识别源语种。
input_audio_formatstring(可选)适用于 qwen3.5-livetranslate-flash-realtime。
用户输入音频格式,可选值:
-
pcm(默认)未压缩的原始音频数据。
-
opus有损压缩音频编码,支持低延迟传输,适用于网络语音场景。
output_audio_formatstring(可选)适用于 qwen3.5-livetranslate-flash-realtime。
输出音频格式,当前仅支持设为pcm。
turn_detectionobject|null(可选)适用于 qwen3.5-livetranslate-flash-realtime。
语音活动检测(VAD,Voice Activity Detection)配置,用于控制语音起止的检测方式:
- 设为配置对象(默认值):启用 VAD 模式。服务端自动检测语音起止,自动提交音频缓冲区并触发翻译响应,客户端无需发送
input_audio_buffer.commit事件。 - 设为
null:启用 Manual 模式。由客户端通过input_audio_buffer.commit事件手动提交音频缓冲区,服务端收到后自动开始生成翻译响应。
属性
typestring(可选)VAD 类型,固定为server_vad。
thresholdfloat(可选)VAD 检测灵敏度。值越低,越容易将微弱声音(包括背景噪音)识别为语音;值越高,需要更清晰、音量更大的语音才能触发。
取值范围:[-1.0, 1.0],默认值为 0.2。
silence_duration_msinteger(可选)语音结束后需保持静音的最短时长(毫秒)。超过该时长后判定语音结束,服务端自动提交音频缓冲区并触发翻译响应。
取值范围:[200, 6000],默认值为 1000。
translationobject(可选)翻译配置。
属性
languagestring(可选)翻译目标语种,可选值:支持的语种。默认值为en。
same_language_skip_optionsobject(可选)qwen3.8-livetranslate-flash-realtime 不支持此参数。
同语种输出配置。当源语种与目标语种相同时,可跳过文本输出、音频输出或两者。仅当翻译目标语种为zh或en时生效。
属性
skip_textboolean(可选)是否在源语种与目标语种相同时跳过文本输出。
skip_audioboolean(可选)是否在源语种与目标语种相同时跳过音频输出。
corpusobject(可选)热词配置,用于提升特定词汇的翻译准确性。
属性
phrasesobject(可选)热词映射表。key 为源语言词汇,value 为目标语言对应翻译。
示例:{"人工智能": "Artificial Intelligence"}
qwen3.8-livetranslate-flash-realtime
{
"type": "session.update",
"session": {
"input_modalities": [
"audio",
"video"
],
"output_modalities": [
"text",
"audio"
],
"audio": {
"input": {
"format": {
"type": "pcm",
"sample_rate": 16000
},
"turn_detection": {
"type": "speaker_detection",
"threshold": 0.5
}
},
"output": {
"voice": "default"
}
},
"enable_voice_clone": true,
"voice_clone_options": {
"frequency": "once"
},
"translation": {
"language": "en",
"corpus": {
"phrases": {
"人工智能": "Artificial Intelligence",
"机器学习": "Machine Learning"
}
}
}
}
}
qwen3.5-livetranslate-flash-realtime
{
"event_id": "event_ToPZqeobitzUJnt3QqtWg",
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "default",
"enable_voice_clone": true,
"voice_clone_options": {
"frequency": "once"
},
"sample_rate": 16000,
"input_audio_format": "pcm",
"output_audio_format": "pcm",
"input_audio_transcription": {
"model": "qwen3-asr-flash-realtime",
"language": "zh"
},
"turn_detection": {
"type": "server_vad",
"threshold": 0.2,
"silence_duration_ms": 1000
},
"translation": {
"language": "en",
"same_language_skip_options": {
"skip_text": false,
"skip_audio": false
},
"corpus": {
"phrases": {
"人工智能": "Artificial Intelligence",
"机器学习": "Machine Learning"
}
}
}
}
}
input_audio_buffer.append
WebSocket 接入时,向输入音频缓冲区追加音频字节。服务端使用此缓冲区检测并决定语音提交时机。
typestring(必选)事件类型,固定为input_audio_buffer.append。
audiostring(必选)Base64 编码的音频数据。
{
"event_id": "event_xxx",
"type": "input_audio_buffer.append",
"audio": "xxx"
}
input_audio_buffer.commit
提交输入音频缓冲区。仅在 Manual 模式(turn_detection设为null)下需要发送此事件;VAD 模式下服务端会自动提交,客户端无需发送。
服务端收到该事件后,会返回input_audio_buffer.committed事件确认,并自动开始生成翻译响应(无需再发送其他事件触发响应)。若音频缓冲区为空,服务端将返回错误事件。
typestring(必选)事件类型,固定为input_audio_buffer.commit。
{
"event_id": "event_xxx",
"type": "input_audio_buffer.commit"
}
input_audio_buffer.clear
清空输入音频缓冲区中尚未提交的音频数据。
typestring(必选)事件类型,固定为input_audio_buffer.clear。
{
"event_id": "event_xxx",
"type": "input_audio_buffer.clear"
}
input_image_buffer.append
WebSocket 接入时,将图像数据添加到图像缓冲区。图像可来自本地文件,或从视频流实时采集。
使用 qwen3.8-livetranslate-flash-realtime 时,先在 session.update 中将 session.input_modalities 设为 ["audio", "video"]。旧请求省略此字段时仍可上传图片,但模型不会处理。
目前对图片输入有以下限制:
- 图像格式必须为 JPG 或 JPEG。建议分辨率为 480p 或 720p以获得最佳性能,最高不超过 1080p;
- 单张图片大小不大于500KB(Base64编码前);
- 图片数据需要经过Base64编码;
- 以不超过每秒 2 张的频率向缓冲区添加图像;
- 发送 input_image_buffer.append 事件前,至少发送过一次 input_audio_buffer.append 事件。
typestring(必选)事件类型,固定为input_image_buffer.append。
imagestring(必选)Base64 编码的图像数据。
{
"event_id": "event_xxx",
"type": "input_image_buffer.append",
"image": "xxx"
}
session.finish
用于结束当前会话。发送此事件后,服务端响应流程:
- 已检测到语音:服务端完成剩余翻译;启用原文识别时,通过 conversation.item.input_audio_transcription.completed 事件返回完整原文。所有音频翻译完成后,发送 session.finished 事件作为会话结束标识。
- 未检测到语音:服务端直接发送
session.finished事件。
客户端监听到 session.finished 事件后,如需播放剩余译音,应先完成本地播放,再主动断开连接。
typestring(必选)事件类型,固定为session.finish。
{
"event_id": "event_xxx",
"type": "session.finish"
}