实时语音识别（Qwen-ASR-Realtime）Java SDK-API参考

本文档介绍如何使用 DashScope Java SDK 调用实时语音识别（Qwen-ASR-Realtime）模型。

前提条件

1. 安装SDK，确保DashScope SDK版本不低于2.22.5。
2. 获取与配置 API Key。
3. 了解WebSocket API。

完整示例

ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm

import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import javax.sound.sampled.LineUnavailableException;
import java.io.File;
import java.io.FileInputStream;
import java.util.Base64;
import java.util.Collections;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicReference;

public class Qwen3AsrRealtimeUsage {
    private static final Logger log = LoggerFactory.getLogger(Qwen3AsrRealtimeUsage.class);
    private static final int AUDIO_CHUNK_SIZE = 1024; // Audio chunk size in bytes
    private static final int SLEEP_INTERVAL_MS = 30;  // Sleep interval in milliseconds

    public static void main(String[] args) throws InterruptedException, LineUnavailableException {
        CountDownLatch finishLatch = new CountDownLatch(1);

        OmniRealtimeParam param = OmniRealtimeParam.builder()
                .model("qwen3-asr-flash-realtime")
                // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
                .url("wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime")
                // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
                // 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：.apikey("sk-xxx")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

        OmniRealtimeConversation conversation = null;
        final AtomicReference<OmniRealtimeConversation> conversationRef = new AtomicReference<>(null);
        conversation = new OmniRealtimeConversation(param, new OmniRealtimeCallback() {
            @Override
            public void onOpen() {
                System.out.println("connection opened");
            }
            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch(type) {
                    case "session.created":
                        System.out.println("start session: " + message.get("session").getAsJsonObject().get("id").getAsString());
                        break;
                    case "conversation.item.input_audio_transcription.completed":
                        System.out.println("transcription: " + message.get("transcript").getAsString());
                        finishLatch.countDown();
                        break;
                    case "input_audio_buffer.speech_started":
                        System.out.println("======VAD Speech Start======");
                        break;
                    case "input_audio_buffer.speech_stopped":
                        System.out.println("======VAD Speech Stop======");
                        break;
                    case "conversation.item.input_audio_transcription.text":
                        System.out.println("transcription: " + message.get("text").getAsString() + message.get("stash").getAsString());
                        break;
                    default:
                        break;
                }
            }
            @Override
            public void onClose(int code, String reason) {
                System.out.println("connection closed code: " + code + ", reason: " + reason);
            }
        });
        conversationRef.set(conversation);
        try {
            conversation.connect();
        } catch (NoApiKeyException e) {
            throw new RuntimeException(e);
        }

        OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
        transcriptionParam.setLanguage("zh");
        transcriptionParam.setInputAudioFormat("pcm");
        transcriptionParam.setInputSampleRate(16000);

        OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
                .transcriptionConfig(transcriptionParam)
                .build();
        conversation.updateSession(config);

        String filePath = "your_audio_file.pcm";
        File audioFile = new File(filePath);
        if (!audioFile.exists()) {
            log.error("Audio file not found: {}", filePath);
            return;
        }

        try (FileInputStream audioInputStream = new FileInputStream(audioFile)) {
            byte[] audioBuffer = new byte[AUDIO_CHUNK_SIZE];
            int bytesRead;
            int totalBytesRead = 0;

            log.info("Starting to send audio data from: {}", filePath);

            // Read and send audio data in chunks
            while ((bytesRead = audioInputStream.read(audioBuffer)) != -1) {
                totalBytesRead += bytesRead;
                byte[] chunk = new byte[bytesRead];
                System.arraycopy(audioBuffer, 0, chunk, 0, bytesRead);
                String audioB64 = Base64.getEncoder().encodeToString(chunk);
                // Send audio chunk to conversation
                conversation.appendAudio(audioB64);

                // Add small delay to simulate real-time audio streaming
                Thread.sleep(SLEEP_INTERVAL_MS);
            }

            log.info("Finished sending audio data. Total bytes sent: {}", totalBytesRead);

        } catch (Exception e) {
            log.error("Error sending audio from file: {}", filePath, e);
        }

        //send session.finish and wait for finish and close
        conversation.endSession();
        log.info("task finished");

        System.exit(0);
    }
}

请求参数

• 以下参数通过OmniRealtimeParam的链式方法设置。

  点击查看示例代码

  OmniRealtimeParam param = OmniRealtimeParam.builder()
                  .model("qwen3-asr-flash-realtime")
                  // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
                  .url("wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime")
                  // 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
                  // 若没有配置环境变量，请用百炼API Key将下行替换为：.apikey("sk-xxx")
                  .apikey(System.getenv("DASHSCOPE_API_KEY"))
                  .build();
  

  参数	类型	是否必须	说明
  model	String	是	指定要使用的模型名称。
  url	String	是	语音识别服务地址： 华北2（北京）地域：wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime。调用时请将{WorkspaceId}替换为真实的Workspace ID。 新加坡地域：wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime。调用时请将{WorkspaceId}替换为真实的业务空间ID。
  apikey	String	否	设置API Key。

• 以下参数通过OmniRealtimeConfig的链式方法设置。

  点击查看示例代码

  OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
          transcriptionParam.setLanguage("zh");
          transcriptionParam.setInputSampleRate(16000);
          transcriptionParam.setInputAudioFormat("pcm");
  
  OmniRealtimeConfig config = OmniRealtimeConfig.builder()
                  .modalities(Collections.singletonList(OmniRealtimeModality.TEXT))
                  .enableTurnDetection( true)
                  .turnDetectionType("server_vad")
                  .turnDetectionThreshold(0.0f)
                  .turnDetectionSilenceDurationMs(400)
                  .transcriptionConfig(transcriptionParam)
                  .build();
  

  参数	类型	是否必须	说明
  modalities	List<OmniRealtimeModality>	是	模型输出模态，固定为[OmniRealtimeModality.TEXT]。
  enableTurnDetection	boolean	否	是否开启服务端语音活动检测（VAD）。关闭后，需手动调用commit()方法触发识别。 默认值：true。 取值范围： true：开启 false：关闭
  turnDetectionType	String	否	服务端VAD类型，固定为 server_vad。
  turnDetectionThreshold	float	否	VAD检测阈值。推荐将该值设为0.0。 默认值：0.5。 取值范围：[-1, 1]。 较低的阈值会提高 VAD 的灵敏度，可能将背景噪音误判为语音。较高的阈值则降低灵敏度，有助于在嘈杂环境中减少误触发。
  turnDetectionSilenceDurationMs	int	否	VAD断句检测阈值（ms）。静音持续时长超过该阈值将被认为是语句结束。推荐将该值设为400。 默认值：800。 取值范围：[200, 6000]。 较低的值（如 300ms）可使模型更快响应，但可能导致在自然停顿处发生不合理的断句。较高的值（如 1200ms）可更好地处理长句内的停顿，但会增加整体响应延迟。
  transcriptionConfig	OmniRealtimeTranscriptionParam	否	语音识别相关配置。

• 以下参数通过OmniRealtimeTranscriptionParam的setter方法设置。

  点击查看示例代码

  OmniRealtimeTranscriptionParam transcriptionParam = new OmniRealtimeTranscriptionParam();
          transcriptionParam.setLanguage("zh");
          transcriptionParam.setInputSampleRate(16000);
          transcriptionParam.setInputAudioFormat("pcm");
  

  参数	类型	是否必须	说明
  language	String	否	音频源语言。 zh：中文（普通话、四川话、闽南语、吴语） yue：粤语 en：英文 ja：日语 de：德语 ko：韩语 ru：俄语 fr：法语 pt：葡萄牙语 ar：阿拉伯语 it：意大利语 es：西班牙语 hi：印地语 id：印尼语 th：泰语 tr：土耳其语 uk：乌克兰语 vi：越南语 cs：捷克语 da：丹麦语 fil：菲律宾语 fi：芬兰语 is：冰岛语 ms：马来语 no：挪威语 pl：波兰语 sv：瑞典语
  inputSampleRate	int	否	音频采样率（Hz）。支持16000和8000。 默认值：16000。 设置为 8000 时，服务端会先升采样到16000Hz再进行识别，可能引入微小延迟。建议仅在源音频为8000Hz（如电话线路）时使用。
  inputAudioFormat	String	否	音频格式。支持pcm和opus。 默认值：pcm。

关键接口

OmniRealtimeConversation类

OmniRealtimeConversation通过import com.alibaba.dashscope.audio.omni.OmniRealtimeConversation;方法引入。

public OmniRealtimeConversation(OmniRealtimeParam param, OmniRealtimeCallback callback)

public void connect() throws NoApiKeyException, InterruptedException

public void updateSession(OmniRealtimeConfig config)

public void appendAudio(String audioBase64)

public void commit()

public void endSession() throws InterruptedException

public void close()

public String getSessionId()

public String getResponseId()

回调接口（OmniRealtimeCallback）

服务端会通过回调的方式，将服务端响应事件和数据返回给客户端。

继承此类并实现相应方法以处理服务端事件。

通过import com.alibaba.dashscope.audio.omni.OmniRealtimeCallback;引入。

public void onOpen()

public abstract void onEvent(JsonObject message)

public abstract void onClose(int code, String reason)