All Products
Search
Document Center

Alibaba Cloud Model Studio:Paraformer Real-time Speech Recognition Python SDK

Last Updated:Nov 20, 2026

This topic describes the parameters and interface details of the Paraformer Real-time Speech Recognition Python SDK.

ImportantThis document applies only to the China (Beijing) region. To use the models, you must use the API Key of the China (Beijing) region.

ImportantAlibaba Cloud Model Studio has launched workspace-specific domains for the China (Beijing) region, which deliver superior performance and higher stability for inference requests. We recommend migrating from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.

{WorkspaceId} must be replaced with your actual Workspace ID. The existing domain still works.

User guide: For model introduction and selection recommendations, see Real-time speech recognition-Fun-ASR/Paraformer.

Prerequisites

You have activated the service and obtained and configured an API Key. We recommend that you configure the API Key in environment variables instead of hardcoding it in your code, to prevent security risks caused by code leakage.

NoteWhen you need to grant temporary access to third-party applications or users, or want to strictly control high-risk operations such as accessing or deleting sensitive data, we recommend using a temporary authentication token.

Compared with a long-term API Key, a temporary authentication token is short-lived (60 s) and highly secure, making it suitable for temporary call scenarios and effectively reducing the risk of API Key leakage.

Usage: In your code, simply replace the API Key originally used for authentication with the obtained temporary authentication token.

Models

paraformer-realtime-v2paraformer-realtime-8k-v2
Applicable Scenario

Scenarios such as live streaming and meetings

Scenarios for recognizing 8 kHz audio, such as call centers and voicemail

Sampling rate

Any

8kHz

Languages

Chinese (including Mandarin Chinese and various dialects), English, Japanese, Korean, German, French, Russian

Supported Chinese dialects: Shanghai dialect, Wu Chinese, Minnan dialect, Northeastern Mandarin, Gansu dialect, Guizhou dialect, Henan dialect, Hubei dialect, Hunan dialect, Jiangxi dialect, Ningxia dialect, Shanxi dialect, Shaanxi dialect, Shandong dialect, Sichuan dialect, Tianjin dialect, Yunnan dialect, Cantonese

Chinese

Punctuation prediction

Enabled by default, no configuration required

Enabled by default, no configuration required

Inverse text normalization (ITN)

Enabled by default, no configuration required

Enabled by default, no configuration required

Custom hotwords

See Customize Hotwords

See Customize Hotwords

Specify the language to recognize

Specified via the language_hints parameter

Not supported

Emotion recognition

Not supported

Click to view usage

Emotion recognition is subject to the following constraints:

  • Only the paraformer-realtime-8k-v2 model is supported.
  • Semantic punctuation must be disabled (it is controlled by semantic_punctuation_enabled in request parameters). Semantic punctuation is disabled by default.
  • Emotion recognition results are only available when the is_sentence_end method of Recognition result (RecognitionResult) returns True.

How to obtain emotion recognition results: The emotion and emotion confidence of the current sentence are obtained via the emo_tag and emo_confidence fields of single-sentence information (Sentence).

QuickStart

Core resource (client.audio.asr) provides non-streaming and bidirectional streaming call interfaces. Please choose the appropriate calling method based on your actual needs:

  • Non-streaming call (recognize_file): Recognizes local files. The SDK automatically sends the audio in chunks and drives the task to completion. Suitable for processing pre-recorded audio.
  • Bidirectional streaming call: Recognizes audio streams directly and outputs results in real time. The audio stream can come from an external device (such as a microphone) or be read from a local file. Suitable for scenarios that require immediate feedback.

Non-streaming calls

Submit a single real-time speech transcription task and obtain the transcription result synchronously by passing in a local file.

image

Call the recognize_file method of Core resource (client.audio.asr) to bind request parameters and pass in the local file path, iterating over server-side events to obtain Recognition result (RecognitionResult).

Click to view the full example

import os
import dashscope

# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
    # 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# 识别本地语音文件:recognize_file自动分块发送音频并驱动到任务结束
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='paraformer-realtime-v2',
        format='wav',
        sample_rate=16000,
        # “language_hints”只支持paraformer-realtime-v2模型
        parameters={'language_hints': ['zh', 'en']}):
    payload = event.get('payload') or {}
    sentence = (payload.get('output') or {}).get('sentence') or {}
    if sentence.get('text') and not sentence.get('heartbeat'):
        print('识别结果:', sentence['text'])

recognize_file yields server-side events (Dict[str, Any]) one by one: the event type is located at event['header']['event'], and the recognized text is located at event['payload']['output']['sentence'] (sentence_end being true indicates that the sentence has ended; begin_time / end_time are timestamps and words contains word-level timestamps — see single-sentence information (Sentence) for other fields). Heartbeat and empty-text events are still yielded and can be ignored as needed.

In a bidirectional streaming session, besides events(), you can use results() to iterate only recognition result frames (returning typed Recognition result (RecognitionResult), with heartbeat frames filtered out). For more information, see the get_sentence method description.

Bidirectional streaming calls

Submit a single real-time speech transcription task and obtain real-time recognition results streamed by iterating over events.

image
  1. Start streaming speech recognition

    Call the recognize method of Core resource (client.audio.asr) to create a recognition session and bind request parameters, then enter the with context (which automatically calls the start method to establish the connection and send the task) to start streaming speech recognition.

  2. Streaming

    Call the session's send_audio_frame method in a loop to send the binary audio stream read from a local file or device (such as a microphone) to the server in segments. Sending and receiving must proceed concurrently: the receiving thread iterates over server-side events via event iteration (events()/results()) and returns recognition results to the client in real time.

    It is recommended that each send contain approximately 100 milliseconds of audio, with the data size kept between 1 KB and 16 KB.

  3. Finish processing

    Call the session's stop method to end speech recognition.

    This method only notifies the server that input has ended; the receiving thread must continue consuming events() until the task-finished event to obtain the final recognition results and statistics. Errors at the ws layer are raised as DashScopeError exceptions, which can be caught with try/except where you send or receive.

Click to view the full example

import os
import signal  # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
    # 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

mic = None
stream = None

# Set recording parameters
sample_rate = 16000  # sampling rate (Hz)
channels = 1  # mono channel
dtype = 'int16'  # data type
format_pcm = 'pcm'  # the format of the audio data
block_size = 3200  # number of frames per buffer

# Real-time speech recognition event receiver
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognition text: ', sentence['text'])
            if sentence.get('sentence_end'):
                print(
                    'Recognition sentence end, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

def signal_handler(sig, frame):
    print('Ctrl+C pressed, stop recognition ...')
    # Stop recognition
    recognition.stop()
    print('Recognition stopped.')
    print(
        '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
        .format(
            recognition.request_id,
            recognition.first_package_delay,
            recognition.last_package_delay,
        ))
    # Forcefully exit the program
    sys.exit(0)

# main function
if __name__ == '__main__':
    print('Initializing ...')

    signal.signal(signal.SIGINT, signal_handler)
    print("Press 'Ctrl+C' to stop recording and recognition...")

    # Call recognition service, you can customize the recognition parameters, like model, format,
    # sample_rate
    with client.audio.asr.recognize(
            model='paraformer-realtime-v2',
            format=format_pcm,
            # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', you can check the supported formats in the document
            sample_rate=sample_rate,
            # support 8000, 16000
            parameters={'semantic_punctuation_enabled': False},
    ) as recognition:
        # Open the microphone
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, recognition)
            try:
                # Send audio from the microphone until "Ctrl+C" is pressed
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close must run inside the pool context to unblock the receiver
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
    # 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

# Real-time speech recognition event receiver
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print(get_timestamp() + ' Recognition text: ', sentence['text'])
            if sentence.get('sentence_end'):
                print(get_timestamp() +
                    'Recognition sentence end, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

with client.audio.asr.recognize(
        model='paraformer-realtime-v2',
        format='wav',
        sample_rate=16000,
        # “language_hints”只支持paraformer-realtime-v2模型
        parameters={'language_hints': ['zh', 'en']},
) as recognition:
    with ThreadPoolExecutor(max_workers=1) as pool:
        receiver = pool.submit(receive_events, recognition)
        try:
            audio_data: bytes = None
            f = open("{YOUR_AUDIO_FILE}", 'rb')
            if os.path.getsize("{YOUR_AUDIO_FILE}"):
                while True:
                    audio_data = f.read(3200)
                    if not audio_data:
                        break
                    else:
                        recognition.send_audio_frame(audio_data)
                    time.sleep(0.1)
            else:
                raise Exception(
                    'The supplied file was empty (zero bytes long)')
            f.close()
            recognition.stop()
            receiver.result()
        finally:
            # close must run inside the pool context to unblock the receiver
            recognition.close()

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.request_id,
        recognition.first_package_delay,
        recognition.last_package_delay,
    ))

Concurrent calls

In Python, due to the global interpreter lock, only one thread can execute Python code at a time (although some performance-oriented libraries may lift this restriction). To make better use of the computing resources of multi-core machines, we recommend using multiprocessing or concurrent.futures.ProcessPoolExecutor. Multithreading significantly increases SDK call latency under high concurrency.

Request parameters

Request parameters are set via the recognize/recognize_file methods of Core resource (client.audio.asr): model, format, sample_rate, vocabulary_id, and disfluency_removal_enabled are named parameters, and the remaining parameters (such as language_hints and semantic_punctuation_enabled) are passed in via the parameters dictionary.

Parameter

Type

Default Value

Required

Description

model

str

-

Yes

The model used for Real-time Speech Recognition (see Models).

sample_rate

int

-

Yes

Set the sample rate of the audio to recognize (in Hz).

Varies by model:

  • paraformer-realtime-v2 supports any sample rate.

  • paraformer-realtime-8k-v2 supports only the 8000 Hz sample rate.

format

str

-

Yes

Set the format of the audio to recognize.

Supported audio formats: pcm, wav, mp3, opus, speex, aac, amr.

opus/speex: must use Ogg encapsulation;

wav: must be PCM encoding;

amr: only the AMR-NB type is supported.

vocabulary_id

str

-

No

Set the hotword ID. It does not take effect if not set. Use this field when setting a hotword ID for v2 and later models.

In this speech recognition session, the hotword information corresponding to this hotword ID will be applied. For more information, see Customize Hotwords.

disfluency_removal_enabled

bool

False

No

Set whether to filter filler words:

  • true: filter filler words

  • false (default): do not filter filler words

language_hints

list[str]

["zh", "en"]

No

Set the language code of the audio to recognize. If the language cannot be determined in advance, you can leave it unset, and the model will automatically detect the language.

Currently supported language codes:

  • zh: Chinese

  • en: English

  • ja: Japanese

  • yue: Cantonese

  • ko: Korean

  • de: German

  • fr: French

  • ru: Russian

This parameter only takes effect for models that support multiple languages (see the Models list).

semantic_punctuation_enabled

bool

False

No

Specifies whether to enable semantic segmentation, disabled by default.

  • true: enables semantic segmentation and disables VAD (Voice Activity Detection) segmentation.

  • false (default): enables VAD (Voice Activity Detection) segmentation and disables semantic segmentation.

Semantic segmentation is more accurate and suitable for meeting transcription; VAD (Voice Activity Detection) segmentation has lower latency and is suitable for interactive scenarios.

By adjusting the semantic_punctuation_enabled parameter, you can flexibly switch the segmentation method of speech recognition to meet the needs of different scenarios.

This parameter only takes effect when the model is v2 or later.

max_sentence_silence

int

800

No

Sets the silence duration threshold (in ms) for VAD (Voice Activity Detection) segmentation.

When the silence duration after a segment of speech exceeds this threshold, the system determines that the sentence has ended.

The parameter ranges from 200 ms to 6000 ms, with a default value of 800 ms.

This parameter only takes effect when the semantic_punctuation_enabled parameter is false (VAD segmentation) and the model is v2 or later.

multi_threshold_mode_enabled

bool

False

No

When this switch is turned on (true), it prevents VAD segmentation from cutting overly long segments. Disabled by default.

This parameter only takes effect when the semantic_punctuation_enabled parameter is false (VAD segmentation) and the model is v2 or later.

punctuation_prediction_enabled

bool

True

No

Specifies whether to automatically add punctuation to recognition results:

  • true (default): Yes

  • false: No

This parameter only takes effect when the model is v2 or later.

heartbeat

bool

False

No

When you need to maintain a long connection with the server, you can control it with this switch:

  • true: keeps the connection to the server uninterrupted when silence audio is continuously sent.

  • false (default): even if silence audio is continuously sent, the connection will be closed after a certain period due to timeout.

    Silence audio refers to content with no sound signal in an audio file or data stream. Silence audio can be generated in multiple ways, for example, using audio editing software such as Audacity or Adobe Audition, or command-line tools such as FFmpeg.

This parameter only takes effect when the model is v2 or later.

This field was introduced in SDK 1.23.1 and is included in version 2.0.1 and later.

inverse_text_normalization_enabled

bool

True

No

Specifies whether to enable ITN (Inverse Text Normalization).

Enabled by default (true). When enabled, Chinese numerals are converted to Arabic numerals.

This parameter only takes effect when the model is v2 or later.

API reference

Core resources (client.audio.asr)

Real-time speech recognition capabilities are mounted on the client.audio.asr resource: recognize creates a bidirectional streaming recognition session (Recognition), and recognize_file performs one-time recognition on local files.

Member methodsMethod signaturesDescription

recognize

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition

Creates a bidirectional streaming recognition session; when entering the with context, it automatically calls start to establish the connection and send the task.

Sending audio and consuming events must be performed concurrently (used together with send_audio_frame, events()/results(), and stop).

recognize_file

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]

Non-streaming call based on a local file: automatically sends audio in chunks and drives the task to completion, producing server-side events one by one. This method requires the recognized file to have read permission.

start

def start(self)

Start speech recognition: establishes the connection, sends the task, and waits for task-started. Automatically called when entering the with context; audio can be sent only after a successful startup.

send_audio_frame

def send_audio_frame(self, buffer: bytes)

Push audio. Each audio chunk pushed should not be too large or too small. We recommend that each audio packet be around 100 ms in duration and between 1KB~16KB in size.

Recognition results are obtained through event iteration (events()/results()).

stop

def stop(self)

Stop speech recognition: only notifies the server that input has ended. The receiving thread must continue to consume events() until the task-finished event.

events / results

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]

Iterate server events: events() yields raw event dict objects (recognition text is located in payload.output.sentence); results() yields only recognition result frames and returns RecognitionResult typed objects (heartbeat frames are filtered out).

close

def close(self)

Closes the recognition session. Automatically called when exiting the with context.

request_id / first_package_delay / last_package_delay

rec.request_id
rec.first_package_delay
rec.last_package_delay

Obtain request_id, first-packet latency (the delay from sending the first audio packet to receiving the first recognition result), and last-packet latency (the time from sending the stop command until the last recognition result is delivered). Use it after the task is complete; it remains readable after the session is closed.

Event iteration (events()/results())

During bidirectional streaming calls, the server returns key process information and data to the client as events. You need to iterate the session's events() (raw event dict objects) or results() (typed recognition result frames) in a receiving thread to process the information or data returned by the server.

Click to view example

# 迭代原始事件:识别文本位于 payload.output.sentence
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('识别文本:', sentence['text'])


# 或只迭代识别结果帧(返回 RecognitionResult,心跳帧已过滤)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('识别文本:', sentence['text'])
Event/iteration methodOutputReturn valueDescription
event["header"]["event"] == "task-started"

task-started event

None

Read internally by start() and stored in last_response when startup returns; it is not yielded again by events().

def events(self) -> Iterator[Dict]

event: server event dict

Iterator

Yields events when the server has a reply. Recognition results are located in payload.output.sentence; these may be heartbeat or empty-text events, which the application can ignore as needed. Please consume them continuously with a single receiving thread and do not create multiple concurrent readers.

def results(self) -> Iterator[RecognitionResult]

result: RecognitionResult

Iterator

Yields only recognition result frames (heartbeat frames are filtered out); iteration ends after all recognition results have been returned.

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)

DashScopeError exception

None

Raised in the sending/receiving thread when an exception occurs; you can catch it with try/except.

event["header"]["event"] == "task-finished"

task-finished event

None

Yielded by events() after the server has completed all recognition, after which iteration ends; you must still read this event after sending stop().

Response results

Recognition result (RecognitionResult)

RecognitionResult represents a recognition result frame yielded by the session's results() iteration (it can be used with both bidirectional streaming calls and non-streaming calls; events() yields raw event dict objects—switch to results() if you need this typed view).

Member methodsMethod signaturesDescription

get_sentence

def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

Obtain the currently recognized sentence and its timestamp information. This method returns a Dict[str, Any] (single-sentence information).

For more information, see Sentence information (Sentence).

request_id

result.request_id

The request_id of the request corresponding to the current event.

is_sentence_end

def is_sentence_end(self) -> bool

Determines whether the current sentence has ended (True when the sentence carries end_time).

Sentence information (Sentence)

The members of the Sentence class are as follows:

Parameter

Type

Description

begin_time

int

The start time of the sentence, in ms.

end_time

int

The end time of the sentence, in ms.

text

str

The recognized text.

words

A list of word timestamp information (Word)

Word timestamp information.

emo_tag

str

The sentiment of the current sentence:

  • positive: positive sentiment, such as happiness and satisfaction

  • negative: negative sentiment, such as anger and gloom

  • neutral: no obvious sentiment

Emotion recognition is subject to the following constraints:

  • Only supported for the paraformer-realtime-8k-v2 model.

  • Semantic punctuation must be disabled (which can be controlled via the request parameter semantic_punctuation_enabled). Semantic punctuation is disabled by default.

  • The sentiment recognition result is displayed only when the is_sentence_end method of Recognition result (RecognitionResult) returns True.

emo_confidence

float

The confidence level of the sentiment recognized for the current sentence, in the range [0.0,1.0]. A larger value indicates higher confidence.

Emotion recognition is subject to the following constraints:

  • Only supported for the paraformer-realtime-8k-v2 model.

  • Semantic punctuation must be disabled (which can be controlled via the request parameter semantic_punctuation_enabled). Semantic punctuation is disabled by default.

  • The sentiment recognition result is displayed only when the is_sentence_end method of Recognition result (RecognitionResult) returns True.

Word timestamp information (Word)

The members of the Word class are as follows:

Parameter

Type

Description

begin_time

int

The start time of the word, in ms.

end_time

int

The end time of the word, in ms.

text

str

The word.

punctuation

str

Punctuation.

More examples

For more examples, see GitHub.

Error codes

If you encounter errors, see Error codes for troubleshooting.

If the problem persists, join the developer group to report the issue and provide the Request ID for further troubleshooting.