Prerequisites
Qwen-Audio-TTS
Service endpoint
The SDK service endpoint is determined by the workspace/region parameters of the Client constructor (corresponding to the addresses below, which include the WorkspaceId). To switch to a different region, change the Client constructor parameters to the values of the target region.
- China (Beijing)
- Singapore
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inferenceReplace {WorkspaceId} with your actual workspace ID.CosyVoice
Service endpoint
The SDK endpoint is determined by the workspace/region parameters of the Client constructor (corresponding to the addresses below, which include WorkspaceId). To switch to a different region, change the Client constructor parameters to the values for that region.
- China (Beijing)
- Singapore
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inferenceReplace {WorkspaceId} with your actual workspace ID.Quick start
Qwen-Audio-TTS
The SDK provides the key interfaces for speech synthesis and supports the following invocation modes:
- Non-streaming: A blocking call that sends the complete text at once and returns the full audio directly. Best suited for short-text speech synthesis.
- Unidirectional streaming: A non-blocking call that sends the complete text at once and receives audio data by iterating over the chunks returned by
stream. Best suited for short-text speech synthesis that requires low latency. - Bidirectional streaming: A non-blocking call that sends text in multiple segments and receives the incrementally synthesized audio stream in real time by iterating over the session's
audio_chunks()/events(). Best suited for long-text speech synthesis that requires low latency.
- Non-streaming
- One-way streaming
- Bidirectional streaming
- dashscope CLI
CosyVoice
The SDK provides the key interfaces for speech synthesis and supports the following calling modes:
- Non-streaming: A blocking call that sends the complete text at once and returns the full audio directly. Best suited for short-text speech synthesis.
- Unidirectional streaming: A non-blocking call that sends the complete text at once and receives data by iterating over the audio chunks returned by
stream. Best suited for short-text scenarios that require low latency. - Bidirectional streaming: A non-blocking call that sends text in multiple segments and receives incrementally synthesized audio in real time by iterating the session's
audio_chunks()/events(). Best suited for long-text scenarios that require low latency.
- Non-streaming
- One-way streaming
- Bidirectional streaming
The text sent in a single call must not exceed 20,000 characters. Exceeding this limit raises a For the complete region table, see Base URL overview.
DashScopeError exception.- dashscope CLI
Request parameters
Qwen-Audio-TTS
The following parameters are set through the synthesize/stream/connect methods of client.audio.tts to control the model, voice, format, and audio characteristics of the synthesis (model, voice, format, sample_rate, volume, rate, pitch, language_hints, and enable_ssml are named parameters; all other parameters are passed through the parameters dictionary).
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | The model name. |
voice | str | Yes | The voice used for speech synthesis.
|
format | str | No | Audio encoding format.Default: mp3.Supports mp3, wav, pcm, and other formats; the sample rate is set through the sample_rate parameter, defaulting to 22050. |
volume | int | No | The volume level.Default value: 50.Valid values: [0, 100]. |
rate | float | No | The speech rate.Default value: 1.0.Valid values: [0.5, 2.0]. |
pitch | float | No | The pitch.Default value: 1.0.Valid values: [0.5, 2.0]. |
bit_rate | int | No | The audio bit rate in kbps. When the audio format is mp3 or opus, use bit_rate to adjust the bit rate.Default value: 32.Valid values: [6, 510].Set bit_rate through the parameters dictionary: |
word_timestamp_enabled | bool | No | Specifies whether to enable word-level timestamps.Default value: false.Available only in streaming output mode. Cloned voices are supported. For supported system voices, see Qwen-Audio-TTS voice list.Set word_timestamp_enabled through the parameters dictionary: |
seed | int | No | A random seed for controlling variation in the synthesis output. When the model version, text, voice, and other parameters are unchanged, using the same seed produces identical results.Default value: 0.Valid values: [0, 65535]. |
language_hints | list[str] | No | For the multilingual and dialect voices of qwen-audio-3.1-tts-flash, this parameter specifies the language or dialect. See multilingual and dialect voice settings for details.
Valid values
|
instruction | str | No | Sets an instruction to control synthesis effects such as dialect, emotion, or role.For usage details, see Instruction control. |
enable_aigc_tag | bool | No | Specifies whether to embed an AIGC watermark in the generated audio. When set to true, the watermark is embedded in audio files of supported formats (wav/mp3/opus).Default value: false.Set enable_aigc_tag, aigc_propagator, and aigc_propagate_id through the parameters dictionary: |
aigc_propagator | str | No | Sets the ContentPropagator field in the AIGC watermark, identifying the content propagator. Takes effect only when enable_aigc_tag is true.Default value: Alibaba Cloud UID.Set through the parameters dictionary. See the enable_aigc_tag example. |
aigc_propagate_id | str | No | Sets the PropagateID field in the AIGC watermark, uniquely identifying a specific propagation action. Takes effect only when enable_aigc_tag is true.Default value: The request ID of the current speech synthesis request.Set through the parameters dictionary. See the enable_aigc_tag example. |
hot_fix | dict | No | Configures pronunciation corrections and text replacements applied before synthesis.Parameters:
|
enable_markdown_filter | bool | No | Whether to enable Markdown filtering. When enabled, the service converts Markdown into text suitable for reading aloud before synthesis.Default: False. Set to True to enable.Use parameters={"enable_markdown_filter": True} to enable it. |
CosyVoice
The following parameters are set through the synthesize/stream/connect methods of client.audio.tts to control the model, voice, format, and audio characteristics of the synthesized audio (model, voice, format, sample_rate, volume, rate, pitch, language_hints, and enable_ssml are named parameters; the other parameters are passed through the parameters dictionary).
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | The model name. |
voice | str | Yes | The voice used for speech synthesis.
|
format | str | No | Audio encoding format.Default: mp3.Supports mp3, wav, pcm, and other formats. The sample rate is set through the sample_rate parameter, defaulting to 22050. |
volume | int | No | The volume level.Default value: 50.Valid values: [0, 100]. |
rate | float | No | The speech rate.Default value: 1.0.Valid values: [0.5, 2.0]. |
pitch | float | No | The pitch.Default value: 1.0.Valid values: [0.5, 2.0]. |
bit_rate | int | No | The audio bit rate in kbps. When the audio format is mp3 or opus, use bit_rate to adjust the bit rate.Default value: 32.Valid values: [6, 510].Set bit_rate through the parameters dictionary: |
word_timestamp_enabled | bool | No | Specifies whether to enable word-level timestamps.Default value: false.Available only in streaming output mode. Supported voices: cloned voices of cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, and system voices marked as supported in CosyVoice Voice list. Cloned voices of other models do not support this feature.Set word_timestamp_enabled through the parameters dictionary: |
seed | int | No | A random seed for controlling variation in the synthesis output. When the model version, text, voice, and other parameters are unchanged, using the same seed produces identical results.Default value: 0.Valid values: [0, 65535]. |
language_hints | list[str] | No | Specifies the target language for speech synthesis to improve output quality.When digit pronunciation, abbreviation expansion, symbol reading, or minority-language synthesis doesn't meet expectations, use this parameter. For example:
Valid values
|
instruction | str | No | Controls synthesis characteristics such as dialect, emotion, or speaking style.For usage details, see Instruction control. |
enable_aigc_tag | bool | No | Specifies whether to embed an AIGC watermark in the generated audio. When set to true, the watermark is embedded in audio files of supported formats (wav/mp3/opus).Default value: false. Only cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 support this feature. enable_aigc_tag, aigc_propagator, and aigc_propagate_id through the parameters dictionary: |
aigc_propagator | str | No | Sets the ContentPropagator field in the AIGC watermark, identifying the content propagator. Takes effect only when enable_aigc_tag is true.Default value: Alibaba Cloud UID.Only cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 support this feature. parameters dictionary. See the enable_aigc_tag example. |
aigc_propagate_id | str | No | Sets the PropagateID field in the AIGC watermark, uniquely identifying a specific propagation action. Takes effect only when enable_aigc_tag is true.Default value: The request ID of the current speech synthesis request.Only cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 support this feature. parameters dictionary. See the enable_aigc_tag example. |
hot_fix | dict | No | Configures pronunciation corrections and text replacements applied before synthesis. This feature isn't supported by cosyvoice-v2.
|
enable_markdown_filter | bool | No | cosyvoice-v2 does not support this feature.
enable_markdown_filter through the parameters dictionary: |
API reference
Qwen-Audio-TTS
See the current Qwen-Audio-TTS Python SDK reference.
Core resource (client.audio.tts)
Resource path: client.audio.tts
Function: WebSocket-based speech synthesis that offers three invocation modes: one-shot synthesis (synthesize), streaming synthesis (stream), and bidirectional streaming sessions (connect).
Invocation entry points
synthesize() - non-streaming
Method signature:| Parameter | Type | Required | Description |
|---|---|---|---|
text | str | Yes | The full text to synthesize. Maximum length: 20,000 characters. |
bytes containing the complete audio data.
Description: This blocking call waits for the synthesis to complete and returns the full audio data at once. It is best suited for short text where real-time streaming is not required. Each synthesize or stream call creates its own session; no instance reuse is needed.
stream() - streaming
Method signature:| Parameter | Type | Required | Description |
|---|---|---|---|
text | str | Yes | The full text to synthesize. Maximum length: 20,000 characters. |
Iterator[bytes] containing the audio data yielded chunk by chunk.
Description: Streaming synthesis sends the complete text at once and yields audio chunk by chunk (Iterator[bytes]). It is best suited for short-text speech synthesis that requires low latency. To submit text in segments, use a bidirectional streaming session (connect).
send_text() - streaming input (session method)
Submit text in segments within a bidirectional streaming session (client.audio.tts.connect(...)).
Method signature:
text is the current text segment to synthesize. Call send_text multiple times to append text. Maximum per call: 20,000 characters. Cumulative maximum: 200,000 characters. Sending text and receiving audio must proceed concurrently (use this together with audio_chunks()/events() and stop).
stop() - end streaming input (session method)
Method signature:audio_chunks()/events() until the remaining text is synthesized and all audio data is returned. Failing to call this method may result in trailing text not being converted to speech.
cancel() - cancel streaming synthesis (session method)
Method signature:Session metrics and responses (session attributes)
first_package_delay:float, the delay in milliseconds from sending text to receiving the first audio chunk. Read it after synthesis completes.usage:dict, the usage information of the most recent synthesis task.last_response:dict, the response message of the most recent synthesis task (containingheader/payloadkeys). The request ID of the most recent request can be retrieved from theheaderofsession.last_response, which is useful for troubleshooting and log correlation.
Sessions and event iteration
Streaming synthesis no longer uses callback interfaces: audio and server events are received through the session's iteration methods. stream()/synthesize() require no session management. The lifecycle of a bidirectional streaming session (client.audio.tts.connect(...)) is: entering the with context opens the connection automatically → multiple send_text() calls → stop() → read all remaining results → exiting the context closes the connection automatically.
audio_chunks() - iterate audio data
Method signature:Iterator[bytes] containing the audio binary data chunks yielded one by one, in the format specified by the format parameter.
Description: Iterate in the receiving thread to receive audio data chunk by chunk; multiple chunks are produced during synthesis. Write the data to a file or feed it to a playback device. Only one events() or audio_chunks() reader is allowed per session.
events() - iterate server events
Method signature:dict, containing header (request information) and payload (output information)) and audio bytes. payload.output contains the event type, original text, and other details. See output field in events() events.
Description: Iterate server replies in the receiving thread. Contains the output information of synthesis events (event type, original text, sentence information); access payload.output directly for details.
Error handling
When an error occurs during synthesis, the WebSocket layer raises aDashScopeError exception, and the connection closes automatically after the exception is raised. Use try/except at the sending or receiving side to catch and log errors for troubleshooting:
Session lifecycle
- Entering the
withcontext opens the connection automatically (initialize audio output streams or open file resources beforehand). - After all text has been synthesized and all audio data has been produced, the
events()/audio_chunks()iteration ends; performance metrics such asfirst_package_delaycan then be read. - Exiting the
withcontext closes the connection automatically (release resources such as audio playback devices afterwards).
output field in events() events
The event dict yielded by the session's events() iteration contains a payload.output field with synthesis event information. Use this field to track synthesis progress and retrieve per-sentence details. The output field structure is as follows:
| Field | Type | Description |
|---|---|---|
type | str | Event type. Values: sentence-begin (sentence synthesis started), sentence-synthesis (sentence synthesis in progress), or sentence-end (sentence synthesis finished). |
original_text | str | The original text of the current sentence. Returned in sentence-begin and sentence-end events. |
sentence | dict | Sentence information. Contains index (sentence sequence number) and words (word list with timestamp information when word_timestamp_enabled is on). |
CosyVoice
See the current CosyVoice Python SDK reference.
Core resource (client.audio.tts)
Resource path: client.audio.tts
Capabilities: WebSocket-based speech synthesis with three calling modes: one-shot synthesis (synthesize), streaming synthesis (stream), and bidirectional streaming sessions (connect).
Calling modes
synthesize() - non-streaming
Method signature:| Parameter | Type | Required | Description |
|---|---|---|---|
text | str | Yes | The full text to synthesize. Maximum length: 20,000 characters. |
bytes containing the complete audio data.
Description: This blocking call waits and returns the complete audio data at once. It is best suited for short text where real-time streaming is not required. Each synthesize or stream call creates its own session; no instance reuse is required.
stream() - streaming
Method signature:| Parameter | Type | Required | Description |
|---|---|---|---|
text | str | Yes | The full text to synthesize. Maximum length: 20,000 characters. |
Iterator[bytes] that yields audio data chunk by chunk.
Description: Streaming synthesis that sends the complete text at once and yields the audio chunk by chunk (Iterator[bytes]). Best suited for short-text scenarios that require low latency. To submit text in segments, use a bidirectional streaming session (connect).
send_text() - streaming input (session method)
Submits text in segments during a bidirectional streaming session (client.audio.tts.connect(...)).
Method signature:
text is the current text segment to synthesize. You can call send_text multiple times to append text. Maximum per call: 20,000 characters. Cumulative maximum: 200,000 characters. Sending text and receiving audio must run concurrently (use send_text together with audio_chunks()/events() and stop).
stop() - end streaming input (session method)
Method signature:audio_chunks()/events() until the remaining text is synthesized and all audio data is returned. Failing to call this method may result in trailing text not being converted to speech.
cancel() - cancel streaming synthesis (session method)
Method signature:Session metrics and response (session properties)
first_package_delay:float, the latency in milliseconds from sending text to receiving the first audio chunk. Read this after synthesis completes.usage:dict, the usage information of the most recent synthesis task.last_response:dict, the response message of the most recent synthesis task (containingheader/payloadkeys). The request ID of the most recent request can be retrieved from theheaderofsession.last_response, useful for troubleshooting and log correlation.
Session and event iteration
Streaming synthesis no longer uses callbacks: audio and server events are received through the session's iteration methods. stream()/synthesize() require no session management. The lifecycle of a bidirectional streaming session (client.audio.tts.connect(...)) is: entering the with context establishes the connection automatically → multiple send_text() calls → stop() → consume all results → exiting the context closes the connection automatically.
audio_chunks() - iterate audio data
Method signature:Iterator[bytes] that yields binary audio data chunks one by one, in the format specified by the format parameter.
Description: Iterate in the receiving thread to receive audio data chunk by chunk; multiple chunks are yielded during synthesis. Write the data to a file or feed it to a playback device. Only one events() or audio_chunks() reader is allowed per session.
events() - iterate server events
Method signature:dict containing header (request information) and payload (output information)) and audio bytes. The payload.output field contains event type, original text, and other details. See output field in events() messages.
Description: Iterate in the receiving thread over server responses, which contain the output information of synthesis events (event type, original text, sentence information, etc.). You can access payload.output directly for details.
Error handling
When an error occurs during synthesis, the WebSocket layer raises aDashScopeError exception, and the connection closes automatically after the exception is raised. Use try/except where you send or receive to catch and log errors for troubleshooting:
Session lifecycle
- The connection is established automatically when entering the
withcontext (you can initialize audio output streams or open file resources beforehand). - After all text has been synthesized and all audio data has been yielded, the
events()/audio_chunks()iteration ends. Performance metrics such asfirst_package_delaycan then be read. - The connection closes automatically when exiting the
withcontext (you can release resources such as audio playback devices afterwards).
output field in events() messages
The event dict yielded by the session's events() iteration contains a payload.output field with synthesis event output information. Use this field to track synthesis progress and retrieve per-sentence details. The structure of the output field is as follows:
| Field | Type | Description |
|---|---|---|
type | str | Event type. Values: sentence-begin (sentence synthesis started), sentence-synthesis (sentence synthesis in progress), or sentence-end (sentence synthesis finished). |
original_text | str | The original text of the current sentence. Returned in sentence-begin and sentence-end events. |
sentence | dict | Sentence information. Contains index (sentence sequence number) and words (word list with timestamp information when word_timestamp_enabled is on). |