Alibaba Cloud Model Studio:Real-time speech recognition - Qwen

International

In the international deployment mode, the endpoint and data storage are located in the Singapore region. Model inference computing resources are dynamically scheduled globally, excluding Mainland China.

To call the following models, use an API key from the Singapore region:

Qwen3-ASR-Flash-Realtime: qwen3-asr-flash-realtime (stable version, alias for qwen3-asr-flash-realtime-2025-10-27), qwen3-asr-flash-realtime-2025-10-27 (snapshot version)

Mainland China

In the Mainland China deployment mode, the endpoint and data storage are located in the Beijing region. Model inference computing resources are limited to Mainland China.

To call the following models, use an API key from the Beijing region:

Qwen3-ASR-Flash-Realtime: qwen3-asr-flash-realtime (the stable version, which is currently an alias for qwen3-asr-flash-realtime-2025-10-27) and qwen3-asr-flash-realtime-2025-10-27 (the snapshot version)

DashScope SDK

WebSocket API

The following example shows how to send a local audio file and retrieve recognition results over a WebSocket connection.

1. Get an API key: Get an API key. For security, set the API key as an environment variable.

2. Write and run code: Implement the complete flow of authentication, connection, sending audio, and receiving results. For more information, see Interaction flow.

   Python

   Before you run the example, install the dependencies by running the following command:

   pip uninstall websocket-client
   pip uninstall websocket
   pip install websocket-client

   Do not name the sample code file websocket.py. Otherwise, the following error may occur: AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?

   # pip install websocket-client
   import os
   import time
   import json
   import threading
   import base64
   import websocket
   import logging
   import logging.handlers
   from datetime import datetime
   
   logger = logging.getLogger(__name__)
   logger.setLevel(logging.DEBUG)
   
   # API keys for the Singapore and Beijing regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key.
   # If you have not configured an environment variable, replace the following line with your Model Studio API key: API_KEY="sk-xxx"
   API_KEY = os.environ.get("DASHSCOPE_API_KEY", "sk-xxx")
   QWEN_MODEL = "qwen3-asr-flash-realtime"
   # The following is the base URL for the Singapore region. If you use a model in the Beijing region, replace the base URL with wss://dashscope.aliyuncs.com/api-ws/v1/realtime.
   baseUrl = "wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime"
   url = f"{baseUrl}?model={QWEN_MODEL}"
   print(f"Connecting to server: {url}")
   
   # Note: If you are not in VAD mode, the cumulative duration of continuously sent audio should not exceed 60s.
   enableServerVad = True
   is_running = True  # Add a running flag.
   
   headers = [
       "Authorization: Bearer " + API_KEY,
       "OpenAI-Beta: realtime=v1"
   ]
   
   def init_logger():
       formatter = logging.Formatter('%(asctime)s|%(levelname)s|%(message)s')
       f_handler = logging.handlers.RotatingFileHandler(
           "omni_tester.log", maxBytes=100 * 1024 * 1024, backupCount=3
       )
       f_handler.setLevel(logging.DEBUG)
       f_handler.setFormatter(formatter)
   
       console = logging.StreamHandler()
       console.setLevel(logging.DEBUG)
       console.setFormatter(formatter)
   
       logger.addHandler(f_handler)
       logger.addHandler(console)
   
   def on_open(ws):
       logger.info("Connected to server.")
   
       # Session update event.
       event_manual = {
           "event_id": "event_123",
           "type": "session.update",
           "session": {
               "modalities": ["text"],
               "input_audio_format": "pcm",
               "sample_rate": 16000,
               "input_audio_transcription": {
                   # Language identifier, optional. If you have clear language information, set it.
                   "language": "zh"
                   # Corpus, optional. If you have a corpus, set it to enhance recognition.
                   # "corpus": {
                   #     "text": ""
                   # }
               },
               "turn_detection": None
           }
       }
       event_vad = {
           "event_id": "event_123",
           "type": "session.update",
           "session": {
               "modalities": ["text"],
               "input_audio_format": "pcm",
               "sample_rate": 16000,
               "input_audio_transcription": {
                   "language": "zh"
               },
               "turn_detection": {
                   "type": "server_vad",
                   "threshold": 0.0,
                   "silence_duration_ms": 400
               }
           }
       }
       if enableServerVad:
           logger.info(f"Sending event: {json.dumps(event_vad, indent=2)}")
           ws.send(json.dumps(event_vad))
       else:
           logger.info(f"Sending event: {json.dumps(event_manual, indent=2)}")
           ws.send(json.dumps(event_manual))
   
   def on_message(ws, message):
       global is_running
       try:
           data = json.loads(message)
           logger.info(f"Received event: {json.dumps(data, ensure_ascii=False, indent=2)}")
           if data.get("type") == "session.finished":
               logger.info(f"Final transcript: {data.get('transcript')}")
               logger.info("Closing WebSocket connection after session finished...")
               is_running = False  # Stop the audio sending thread.
               ws.close()
       except json.JSONDecodeError:
           logger.error(f"Failed to parse message: {message}")
   
   def on_error(ws, error):
       logger.error(f"Error: {error}")
   
   def on_close(ws, close_status_code, close_msg):
       logger.info(f"Connection closed: {close_status_code} - {close_msg}")
   
   def send_audio(ws, local_audio_path):
       time.sleep(3)  # Wait for the session update to complete.
       global is_running
   
       with open(local_audio_path, 'rb') as audio_file:
           logger.info(f"Start reading the file: {datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]}")
           while is_running:
               audio_data = audio_file.read(3200)  # ~0.1s PCM16/16kHz
               if not audio_data:
                   logger.info(f"Finished reading the file: {datetime.now().strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]}")
                   if ws.sock and ws.sock.connected:
                       if not enableServerVad:
                           commit_event = {
                               "event_id": "event_789",
                               "type": "input_audio_buffer.commit"
                           }
                           ws.send(json.dumps(commit_event))
                       finish_event = {
                           "event_id": "event_987",
                           "type": "session.finish"
                       }
                       ws.send(json.dumps(finish_event))
                   break
   
               if not ws.sock or not ws.sock.connected:
                   logger.info("The WebSocket is closed. Stop sending audio.")
                   break
   
               encoded_data = base64.b64encode(audio_data).decode('utf-8')
               eventd = {
                   "event_id": f"event_{int(time.time() * 1000)}",
                   "type": "input_audio_buffer.append",
                   "audio": encoded_data
               }
               ws.send(json.dumps(eventd))
               logger.info(f"Sending audio event: {eventd['event_id']}")
               time.sleep(0.1)  # Simulate real-time collection.
   
   # Initialize the logger.
   init_logger()
   logger.info(f"Connecting to WebSocket server at {url}...")
   
   local_audio_path = "your_audio_file.pcm"
   ws = websocket.WebSocketApp(
       url,
       header=headers,
       on_open=on_open,
       on_message=on_message,
       on_error=on_error,
       on_close=on_close
   )
   
   thread = threading.Thread(target=send_audio, args=(ws, local_audio_path))
   thread.start()
   ws.run_forever()

   Java

   Before you run the example, install the Java-WebSocket dependency:

   Maven

   <dependency>
       <groupId>org.java-websocket</groupId>
       <artifactId>Java-WebSocket</artifactId>
       <version>1.5.6</version>
   </dependency>

   Gradle

   implementation 'org.java-websocket:Java-WebSocket:1.5.6'

   import org.java_websocket.client.WebSocketClient;
   import org.java_websocket.handshake.ServerHandshake;
   import org.json.JSONObject;
   
   import java.net.URI;
   import java.nio.file.Files;
   import java.nio.file.Paths;
   import java.util.Base64;
   import java.util.concurrent.atomic.AtomicBoolean;
   import java.util.logging.*;
   
   public class QwenASRRealtimeClient {
   
       private static final Logger logger = Logger.getLogger(QwenASRRealtimeClient.class.getName());
       // API keys for the Singapore and Beijing regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key.
       // If you have not configured an environment variable, replace the following line with your Model Studio API key: private static final String API_KEY = "sk-xxx"
       private static final String API_KEY = System.getenv().getOrDefault("DASHSCOPE_API_KEY", "sk-xxx");
       private static final String MODEL = "qwen3-asr-flash-realtime";
   
       // Controls whether to use VAD mode.
       private static final boolean enableServerVad = true;
   
       private static final AtomicBoolean isRunning = new AtomicBoolean(true);
       private static WebSocketClient client;
   
       public static void main(String[] args) throws Exception {
           initLogger();
   
           // The following is the base URL for the Singapore region. If you use a model in the Beijing region, replace the base URL with wss://dashscope.aliyuncs.com/api-ws/v1/realtime.
           String baseUrl = "wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime";
           String url = baseUrl + "?model=" + MODEL;
           logger.info("Connecting to server: " + url);
   
           client = new WebSocketClient(new URI(url)) {
               @Override
               public void onOpen(ServerHandshake handshake) {
                   logger.info("Connected to server.");
                   sendSessionUpdate();
               }
   
               @Override
               public void onMessage(String message) {
                   try {
                       JSONObject data = new JSONObject(message);
                       String eventType = data.optString("type");
   
                       logger.info("Received event: " + data.toString(2));
   
                       // When the finish event is received, stop the sending thread and close the connection.
                       if ("session.finished".equals(eventType)) {
                           logger.info("Final transcript: " + data.optString("transcript"));
                           logger.info("Closing WebSocket connection after session finished...");
   
                           isRunning.set(false); // Stop the audio sending thread.
                           if (this.isOpen()) {
                               this.close(1000, "ASR finished");
                           }
                       }
                   } catch (Exception e) {
                       logger.severe("Failed to parse message: " + message);
                   }
               }
   
               @Override
               public void onClose(int code, String reason, boolean remote) {
                   logger.info("Connection closed: " + code + " - " + reason);
               }
   
               @Override
               public void onError(Exception ex) {
                   logger.severe("Error: " + ex.getMessage());
               }
           };
   
           // Add request headers.
           client.addHeader("Authorization", "Bearer " + API_KEY);
           client.addHeader("OpenAI-Beta", "realtime=v1");
   
           client.connectBlocking(); // Block until the connection is established.
   
           // Replace with the path of the audio file to recognize.
           String localAudioPath = "your_audio_file.pcm";
           Thread audioThread = new Thread(() -> {
               try {
                   sendAudio(localAudioPath);
               } catch (Exception e) {
                   logger.severe("Audio sending thread error: " + e.getMessage());
               }
           });
           audioThread.start();
       }
   
       /** Session update event (enable/disable VAD). */
       private static void sendSessionUpdate() {
           JSONObject eventNoVad = new JSONObject()
                   .put("event_id", "event_123")
                   .put("type", "session.update")
                   .put("session", new JSONObject()
                           .put("modalities", new String[]{"text"})
                           .put("input_audio_format", "pcm")
                           .put("sample_rate", 16000)
                           .put("input_audio_transcription", new JSONObject()
                                   .put("language", "zh"))
                           .put("turn_detection", JSONObject.NULL) // Manual mode.
                   );
   
           JSONObject eventVad = new JSONObject()
                   .put("event_id", "event_123")
                   .put("type", "session.update")
                   .put("session", new JSONObject()
                           .put("modalities", new String[]{"text"})
                           .put("input_audio_format", "pcm")
                           .put("sample_rate", 16000)
                           .put("input_audio_transcription", new JSONObject()
                                   .put("language", "zh"))
                           .put("turn_detection", new JSONObject()
                                   .put("type", "server_vad")
                                   .put("threshold", 0.0)
                                   .put("silence_duration_ms", 400))
                   );
   
           if (enableServerVad) {
               logger.info("Sending event (VAD):\n" + eventVad.toString(2));
               client.send(eventVad.toString());
           } else {
               logger.info("Sending event (Manual):\n" + eventNoVad.toString(2));
               client.send(eventNoVad.toString());
           }
       }
   
       /** Send the audio file stream. */
       private static void sendAudio(String localAudioPath) throws Exception {
           Thread.sleep(3000); // Wait for the session to be ready.
           byte[] allBytes = Files.readAllBytes(Paths.get(localAudioPath));
           logger.info("Start reading the file.");
   
           int offset = 0;
           while (isRunning.get() && offset < allBytes.length) {
               int chunkSize = Math.min(3200, allBytes.length - offset);
               byte[] chunk = new byte[chunkSize];
               System.arraycopy(allBytes, offset, chunk, 0, chunkSize);
               offset += chunkSize;
   
               if (client != null && client.isOpen()) {
                   String encoded = Base64.getEncoder().encodeToString(chunk);
                   JSONObject eventd = new JSONObject()
                           .put("event_id", "event_" + System.currentTimeMillis())
                           .put("type", "input_audio_buffer.append")
                           .put("audio", encoded);
   
                   client.send(eventd.toString());
                   logger.info("Sending audio event: " + eventd.getString("event_id"));
               } else {
                   break; // Avoid sending after disconnection.
               }
   
               Thread.sleep(100); // Simulate real-time sending.
           }
   
           logger.info("Finished reading the file.");
   
           if (client != null && client.isOpen()) {
               // A commit is required in non-VAD mode.
               if (!enableServerVad) {
                   JSONObject commitEvent = new JSONObject()
                           .put("event_id", "event_789")
                           .put("type", "input_audio_buffer.commit");
                   client.send(commitEvent.toString());
                   logger.info("Sent commit event for manual mode.");
               }
   
               JSONObject finishEvent = new JSONObject()
                       .put("event_id", "event_987")
                       .put("type", "session.finish");
               client.send(finishEvent.toString());
               logger.info("Sent finish event.");
           }
       }
   
       /** Initialize the logger. */
       private static void initLogger() {
           logger.setLevel(Level.ALL);
           Logger rootLogger = Logger.getLogger("");
           for (Handler h : rootLogger.getHandlers()) {
               rootLogger.removeHandler(h);
           }
   
           Handler consoleHandler = new ConsoleHandler();
           consoleHandler.setLevel(Level.ALL);
           consoleHandler.setFormatter(new SimpleFormatter());
           logger.addHandler(consoleHandler);
       }
   }

   Node.js

   Before you run the example, install the dependency by running the following command:

   npm install ws

   /**
    * Qwen-ASR Realtime WebSocket Client (Node.js version)
    * Features:
    * - Supports VAD and Manual modes.
    * - Sends session.update to start a session.
    * - Continuously sends input_audio_buffer.append audio chunks.
    * - Sends input_audio_buffer.commit in Manual mode.
    * - Sends a session.finish event.
    * - Closes the connection after receiving a session.finished event.
    */
   
   import WebSocket from 'ws';
   import fs from 'fs';
   
   // ===== Configuration =====
   // API keys for the Singapore and Beijing regions are different. To get an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key.
   // If you have not configured an environment variable, replace the following line with your Model Studio API key: const API_KEY = "sk-xxx"
   const API_KEY = process.env.DASHSCOPE_API_KEY || 'sk-xxx';
   const MODEL = 'qwen3-asr-flash-realtime';
   const enableServerVad = true; // true for VAD mode, false for Manual mode
   const localAudioPath = 'your_audio_file.pcm'; // Path to the PCM16, 16 kHz audio file
   
   // The following is the base URL for the Singapore region. If you use a model in the Beijing region, replace the base URL with wss://dashscope.aliyuncs.com/api-ws/v1/realtime.
   const baseUrl = 'wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime';
   const url = `${baseUrl}?model=${MODEL}`;
   
   console.log(`Connecting to server: ${url}`);
   
   // ===== Status Control =====
   let isRunning = true;
   
   // ===== Establish Connection =====
   const ws = new WebSocket(url, {
       headers: {
           'Authorization': `Bearer ${API_KEY}`,
           'OpenAI-Beta': 'realtime=v1'
       }
   });
   
   // ===== Event Binding =====
   ws.on('open', () => {
       console.log('[WebSocket] Connected to server.');
       sendSessionUpdate();
       // Start the audio sending thread.
       sendAudio(localAudioPath);
   });
   
   ws.on('message', (message) => {
       try {
           const data = JSON.parse(message);
           console.log('[Received Event]:', JSON.stringify(data, null, 2));
   
           // Received finish event.
           if (data.type === 'session.finished') {
               console.log(`[Final Transcript] ${data.transcript}`);
               console.log('[Action] Closing WebSocket connection after session finished...');
               
               if (ws.readyState === WebSocket.OPEN) {
                   ws.close(1000, 'ASR finished');
               }
           }
       } catch (e) {
           console.error('[Error] Failed to parse message:', message);
       }
   });
   
   ws.on('close', (code, reason) => {
       console.log(`[WebSocket] Connection closed: ${code} - ${reason}`);
   });
   
   ws.on('error', (err) => {
       console.error('[WebSocket Error]', err);
   });
   
   // ===== Session Update =====
   function sendSessionUpdate() {
       const eventNoVad = {
           event_id: 'event_123',
           type: 'session.update',
           session: {
               modalities: ['text'],
               input_audio_format: 'pcm',
               sample_rate: 16000,
               input_audio_transcription: {
                   language: 'zh'
               },
               turn_detection: null
           }
       };
   
       const eventVad = {
           event_id: 'event_123',
           type: 'session.update',
           session: {
               modalities: ['text'],
               input_audio_format: 'pcm',
               sample_rate: 16000,
               input_audio_transcription: {
                   language: 'zh'
               },
               turn_detection: {
                   type: 'server_vad',
                   threshold: 0.0,
                   silence_duration_ms: 400
               }
           }
       };
   
       if (enableServerVad) {
           console.log('[Send Event] VAD Mode:\n', JSON.stringify(eventVad, null, 2));
           ws.send(JSON.stringify(eventVad));
       } else {
           console.log('[Send Event] Manual Mode:\n', JSON.stringify(eventNoVad, null, 2));
           ws.send(JSON.stringify(eventNoVad));
       }
   }
   
   // ===== Send Audio File Stream =====
   function sendAudio(audioPath) {
       setTimeout(() => {
           console.log(`[File Read Start] ${audioPath}`);
           const buffer = fs.readFileSync(audioPath);
   
           let offset = 0;
           const chunkSize = 3200; // Approx. 0.1s of PCM16 audio
   
           function sendChunk() {
               if (!isRunning) return;
               if (offset >= buffer.length) {
                   isRunning = false; // Stop sending audio.
                   console.log('[File Read End]');
                   if (ws.readyState === WebSocket.OPEN) {
                       if (!enableServerVad) {
                           const commitEvent = {
                               event_id: 'event_789',
                               type: 'input_audio_buffer.commit'
                           };
                           ws.send(JSON.stringify(commitEvent));
                           console.log('[Send Commit Event]');
                       }
   
                       const finishEvent = {
                           event_id: 'event_987',
                           type: 'session.finish'
                       };
                       ws.send(JSON.stringify(finishEvent));
                       console.log('[Send Finish Event]');
                   }
                   
                   return;
               }
   
               if (ws.readyState !== WebSocket.OPEN) {
                   console.log('[Stop] WebSocket is not open.');
                   return;
               }
   
               const chunk = buffer.slice(offset, offset + chunkSize);
               offset += chunkSize;
   
               const encoded = chunk.toString('base64');
               const appendEvent = {
                   event_id: `event_${Date.now()}`,
                   type: 'input_audio_buffer.append',
                   audio: encoded
               };
   
               ws.send(JSON.stringify(appendEvent));
               console.log(`[Send Audio Event] ${appendEvent.event_id}`);
   
               setTimeout(sendChunk, 100); // Simulate real-time sending.
           }
   
           sendChunk();
       }, 3000); // Wait for session configuration to complete.
   }