ASR real-time speech recognition API reference-WebSocket API

Connect to the Fun-ASR real-time speech recognition service over WebSocket. This topic covers the service endpoints, request headers, and interaction flow. User guide: For an introduction to the model and selection guidance, see Speech-to-text. For sample code, see Real-time speech recognition.

The DashScope SDK supports Java and Python only. For other languages, connect to the service directly over WebSocket.

Service endpoint

Use one of the following WebSocket URLs:

International

wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference

China (Mainland)

wss://dashscope.aliyuncs.com/api-ws/v1/inferenceImportant

The URL must use the wss:// protocol. Provide your API key in the Authorization request header (see Request headers).

Request headers

Include the following headers in your request:

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format Bearer . Replace with your API key.
user-agent	string	No	Client identifier that the server uses to trace the request origin.
X-DashScope-WorkSpace	string	No	Alibaba Cloud Model Studio workspace ID.
X-DashScope-DataInspection	string	No	Whether to enable data inspection. Omit this header by default; set it to enable only when required.

Important

The Authorization header is validated during the WebSocket handshake. If the API key is invalid or missing, the handshake fails with HTTP 401 or 403.

Interaction flow

For detailed descriptions of client events and server events, see Client events and Server-side events.

The client and server exchange messages in the following sequence:

1. Establish a connection: The client opens a WebSocket connection to the server.

2. Start the task: The client sends a run-task directive and waits for the server's task-started event, which indicates that the task is ready and the client can proceed to the next steps.

3. Send the audio stream: The client streams binary audio (mono only) while continuously receiving result-generated events from the server. Each event contains speech recognition results.

4. Signal task completion: The client sends a finish-task directive to instruct the server to end the task, and continues to receive result-generated events.

5. End the task: The client receives a task-finished event from the server, which signals that the task has ended.

6. Close the connection: The client closes the WebSocket connection.