LiveTranslate Java SDK

用户指南：教程和完整示例请参见实时翻译。

配置概览

三个 Builder 对象控制一个翻译会话：

OmniRealtimeParam          --> 连接配置：模型、端点、API key
  +-- OmniRealtimeConfig   --> 会话配置：音频格式、音色、输出模态
       +-- OmniRealtimeTranslationParam  --> 翻译配置：目标语言、自定义术语

将 OmniRealtimeParam 传入构造函数。连接成功后，调用 updateSession() 并传入 OmniRealtimeConfig 来设置音频和翻译选项。如果不调用 updateSession()，则使用默认值。

请求参数

OmniRealtimeParam

使用 OmniRealtimeParam.builder() 构建连接参数。

示例代码

OmniRealtimeParam param = OmniRealtimeParam.builder()
  .model("qwen3.5-livetranslate-flash-realtime")
  .url("wss://dashscope.aliyuncs.com/api-ws/v1/realtime")
  // 如果未设置环境变量，请将下一行替换为您的 API key：.apikey("YOUR_API_KEY")
  .apikey(System.getenv("DASHSCOPE_API_KEY"))
  .build();

参数	类型	必选	说明
`model`	`String`	是	模型名称。推荐使用 `qwen3.5-livetranslate-flash-realtime`。`qwen3-livetranslate-flash-realtime` 为旧版模型。
`url`	`String`	是	WebSocket 端点。使用 `wss://dashscope.aliyuncs.com/api-ws/v1/realtime`。
`apikey`	`String`	否	API key。默认读取 `DASHSCOPE_API_KEY` 环境变量。

OmniRealtimeConfig

使用 OmniRealtimeConfig.builder() 构建会话参数，然后调用 conversation.updateSession(config)。

示例代码

// 设置自定义翻译术语
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
  .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
  .voice("Cherry")
  .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
  .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
  .InputAudioTranscription("qwen3-asr-flash-realtime")
  .translationConfig(OmniRealtimeTranslationParam.builder()
    .language("en")
    .corpus(OmniRealtimeTranslationParam.Corpus.builder()
      .phrases(phrases)
      .build())
    .build())
  .build();

conversation.updateSession(config);

参数	类型	必选	说明
`modalities`	`List<OmniRealtimeModality>`	否	输出模态。默认值：`[AUDIO, TEXT]`。设置为 `[TEXT]` 则仅输出文本。
`voice`	`String`	否	合成语音的音色。默认值：`Cherry`。参见支持的音色。
`inputAudioFormat`	`OmniRealtimeAudioFormat`	否	输入音频格式。默认值：`PCM_16000HZ_MONO_16BIT`。
`outputAudioFormat`	`OmniRealtimeAudioFormat`	否	输出音频格式。默认值：`PCM_24000HZ_MONO_16BIT`。
`InputAudioTranscription`	`String`	否	用于转录输入语音的 ASR 模型。设置为 `qwen3-asr-flash-realtime` 可在翻译的同时接收源语言转录结果。注意：此方法名首字母大写（`InputAudioTranscription`），调用时请严格按此拼写。
`translationConfig`	`OmniRealtimeTranslationParam`	否	翻译配置。参见下方 OmniRealtimeTranslationParam。

OmniRealtimeTranslationParam

使用 OmniRealtimeTranslationParam.builder() 构建翻译参数。

示例代码

// 设置翻译术语
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");  // 源语言词汇：目标语言译文
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeTranslationParam translationParam = OmniRealtimeTranslationParam.builder()
  .language("en")  // 目标语言代码
  .corpus(OmniRealtimeTranslationParam.Corpus.builder()
    .phrases(phrases)
    .build())
  .build();

参数	类型	必选	说明
`language`	`String`	否	目标语言代码。默认值：`en`。参见支持的语种。
`corpus`	`Corpus`	否	自定义术语表，用于领域特定术语。
`corpus.phrases`	`Map<String, Object>`	否	术语映射。Key 为源语言术语，Value 为目标语言译文。示例：`{"Inteligencia Artificial": "Artificial Intelligence"}`

核心接口

OmniRealtimeConversation

管理 WebSocket 连接和音频流。 Import：com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

方法	说明
`OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback)`	创建会话，传入连接参数和事件回调。
`void connect()`	建立 WebSocket 连接。触发 session.created 和 session.updated 事件。可能抛出 `NoApiKeyException`、`InterruptedException`。
`void updateSession(OmniRealtimeConfig config)`	更新会话配置。触发 session.updated 事件。未指定的参数使用默认值。
`void appendAudio(String audioBase64)`	发送 Base64 编码的音频数据块。服务端自动检测语音边界并触发翻译。
`void endSession()`	结束会话。服务端会完成进行中的翻译，然后发送 session.finished 事件。可能抛出 `InterruptedException`。
`void close(int code, String reason)`	停止任务并关闭 WebSocket 连接。
`String getSessionId()`	返回会话 ID。
`String getResponseId()`	返回最新服务端响应的响应 ID。
`long getFirstTextDelay()`	返回最新响应的首次文本延迟（毫秒）。
`long getFirstAudioDelay()`	返回最新响应的首次音频延迟（毫秒）。

OmniRealtimeCallback

处理 WebSocket 上的服务端事件。继承此类并实现各方法。 Import：com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

方法	参数	说明
`void onOpen()`	无	WebSocket 连接建立时调用。
`abstract void onEvent(JsonObject message)`	`message`：包含服务端事件的 JSON 对象。	每收到一个服务端事件时调用。解析 `type` 字段以识别事件类型。
`abstract void onClose(int code, String reason)`	`code`：WebSocket 状态码。`reason`：关闭原因描述。	WebSocket 关闭时调用。

onEvent 中的常见事件类型：

事件类型	说明
`input_audio_buffer.speech_started`	检测到音频流中的语音。
`input_audio_buffer.speech_stopped`	检测到语音片段结束。
`conversation.item.input_audio_transcription.completed`	源语言转录就绪。通过 `message.get("transcript")` 读取。需要设置 `InputAudioTranscription`。
`response.audio_transcript.done`	翻译文本就绪。通过 `message.get("transcript")` 读取。
`response.audio.delta`	翻译音频数据块可用。通过 `message.get("delta")` 读取 Base64 编码的音频。
`error`	发生错误。通过 `message.get("error").getAsJsonObject().get("message")` 读取详情。

​配置概览

​请求参数

​OmniRealtimeParam

​OmniRealtimeConfig

​OmniRealtimeTranslationParam

​核心接口

​OmniRealtimeConversation

​OmniRealtimeCallback

​相关参考

配置概览

请求参数

OmniRealtimeParam

OmniRealtimeConfig

OmniRealtimeTranslationParam

核心接口

OmniRealtimeConversation

OmniRealtimeCallback

相关参考