本文档介绍如何使用 DashScope Java SDK 调用实时音视频翻译(Qwen-LiveTranslate-Realtime)模型。
前提条件
- 安装SDK,确保DashScope SDK版本不低于2.22.5。
- 获取与配置 API Key。
- 了解实时语音/音视频翻译-千问。
请求参数
- 以下参数通过
OmniRealtimeParam的链式方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
model | String | 是 | 指定要使用的模型名称,推荐使用qwen3.5-livetranslate-flash-realtime。 |
url | String | 是 | 服务地址,固定为 wss://maas.qianwenaiapi.com/api-ws/v1/realtime。 |
apikey | String | 否 | 设置API Key。 |
- 以下参数通过
OmniRealtimeConfig的链式方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
modalities | List<OmniRealtimeModality> | 否 | 模型输出模态。 默认值: [OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT]。取值范围:
|
voice | String | 是 | 生成音频的音色。 默认值: Tina。可选值:参见支持的音色。 |
inputAudioFormat | OmniRealtimeAudioFormat | 否 | 输入音频格式。 默认值: OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT。 |
outputAudioFormat | OmniRealtimeAudioFormat | 否 | 输出音频格式。 默认值: OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT。 |
InputAudioTranscription | String | 否 | 输入音频转录模型。如需输出原文转录,则必须设置此参数。 可选值: qwen3-asr-flash-realtime。 |
translationConfig | OmniRealtimeTranslationParam | 否 | 翻译相关配置。 |
enableTurnDetection | boolean | 否 | 是否启用 VAD(语音活动检测)。 默认值: true,即启用 VAD 模式,服务端自动检测语音起止并自动触发翻译。设为 false可切换为 Manual 模式,由客户端通过commit()方法手动提交音频。详细参数说明参见turn_detection object (可选) 语音活动检测(VAD,Voice Activity Detection)配置,用于控制语音起止的检测方式: 设为配置对象(默认值):启用 VAD 模式。服务端自动检测语音起止,自动提交音频缓冲区并触发翻译响应,客户端无需发送input_audio_buffer.commit事件。 设为null:启用 Manual 模式。由客户端通过input_audio_buffer.commit事件手动提交音频缓冲区,服务端收到后自动开始生成翻译响应。 属性 type string (可选) VAD 类型,固定为server_vad。 threshold float (可选) VAD 检测灵敏度。值越低,越容易将微弱声音(包括背景噪音)识别为语音;值越高,需要更清晰、音量更大的语音才能触发。 取值范围:[-1.0, 1.0],默认值为 0.2。 silence_duration_ms integer (可选) 语音结束后需保持静音的最短时长(毫秒)。超过该时长后判定语音结束,服务端自动提交音频缓冲区并触发翻译响应。 取值范围:[200, 6000],默认值为 1000。。 |
| 扩展会话参数 |
OmniRealtimeConfig.builder().parameters(Map) 传入。Map 中的键会直接写入 session。例如,开启实时声音复刻时,先构造以下参数:
.voice("default"),并加入 .parameters(parameters)。保留原有语种和音频设置,构建后调用 conversation.updateSession(config)。复刻频率与音色的搭配见声音复刻。
- 以下参数通过OmniRealtimeTranslationParam的链式方法设置。
点击查看示例代码
点击查看示例代码
| 参数 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
language | String | 否 | 翻译目标语言代码。 默认值: en。可选值:参见支持的语种。 |
corpus | OmniRealtimeTranslationParam.Corpus | 否 | 热词配置,用于提升特定词汇的翻译准确性。 |
corpus.phrases | Map<String, Object> | 否 | 热词映射表。key 为源语言词汇,value 为目标语言对应翻译。 示例: {"人工智能": "Artificial Intelligence"} |
关键接口
OmniRealtimeConversation类
OmniRealtimeConversation通过import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;方法引入。
| 方法签名 | 服务端响应事件(通过回调下发) | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | 无 | 构造方法。 |
| 示例 2 请参见表格下方 | 服务端事件 > 会话已创建 服务端事件 > 会话配置已更新 | 和服务端创建连接。 |
| 示例 3 请参见表格下方 | 服务端事件 > 会话配置已更新 | 用于更新会话配置,建议在连接建立后首先调用该方法进行设置。若未调用该方法,系统将使用默认配置。只需关注OmniRealtimeConfig中涉及的参数。 |
| 示例 4 请参见表格下方 | 无 | 将Base64编码后的音频数据片段追加到云端输入音频缓冲区。服务端会自动检测语音起止并触发翻译。 |
| 示例 5 请参见表格下方 | input_audio_buffer.committed > 输入音频缓冲区已提交 | Manual 模式下,提交之前通过appendAudio方法追加到云端缓冲区的音频,服务端收到后自动开始生成翻译响应。VAD 模式下无需调用此方法,服务端会自动提交。 |
| 示例 6 请参见表格下方 | input_audio_buffer.cleared > 输入音频缓冲区已清空 | 清空当前云端缓冲区中尚未提交的音频数据。 |
| 示例 7 请参见表格下方 | session.finished > 服务端完成语音翻译,结束会话 | 通知服务端结束会话,服务端收到会话结束通知后将完成最后的语音翻译。 |
| 示例 8 请参见表格下方 | 无 | 终止任务,并关闭连接。 |
| 示例 9 请参见表格下方 | 无 | 获取当前任务的session_id。 |
| 示例 10 请参见表格下方 | 无 | 获取最近一次response的response_id。 |
| 示例 11 请参见表格下方 | 无 | 获取最近一次响应的首个文本延迟(毫秒)。 |
| 示例 12 请参见表格下方 | 无 | 获取最近一次响应的首个音频延迟(毫秒)。 |
回调接口(OmniRealtimeCallback)
服务端会通过回调的方式,将服务端响应事件和数据返回给客户端。
继承此类并实现相应方法以处理服务端事件。
通过import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;引入。
| 方法签名 | 参数 | 说明 |
|---|---|---|
| 示例 1 请参见表格下方 | 无 | WebSocket连接成功建立时触发。 |
| 示例 2 请参见表格下方 | message:服务端事件 | 收到服务端事件时触发。 |
| 示例 3 请参见表格下方 | code:状态码 reason:WebSocket连接关闭时的日志信息 | WebSocket连接关闭时触发。 |
完整示例
以下示例展示如何从麦克风实时录音并进行翻译。
麦克风实时翻译示例代码
麦克风实时翻译示例代码