Prerequisites
Requires DashScope Python SDK 2.0.1 or later.
Quick start
Request parameters
The following request parameters can be set with the connect method of client.audio.realtime.
Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | Model name (see Supported models). |
ws_url | str | No | Session endpoint. If omitted, it is derived automatically from the Client constructor parameters |
update_session method (named parameters are passed directly; other parameters are passed through to the session object of the session.update event).
Parameter | Type | Required | Description |
|---|---|---|---|
voice | str | Yes | The voice for speech synthesis. For more information, see Qwen-TTS voice list. |
language_type | str | No | Specifies the language of the synthesized audio. The default value is
|
mode | str | No | The interaction mode. Valid values:
|
response_format | str | No | The format of the audio output from the model. Supported formats:
|
sample_rate | int | No | The sample rate of the audio output from the model, in Hz. Supported sample rates:
|
speech_rate | float | No | The speech rate of the audio. A value of 1.0 is the normal speed. A value less than 1.0 is slower, and a value greater than 1.0 is faster. Default value: 1.0. Valid range: [0.5, 2.0]. |
volume | int | No | The volume of the audio. Valid range: [0, 100]. |
pitch_rate | float | No | The pitch of the synthesized audio. Default value: 1.0. Valid range: [0.5, 2.0]. |
bit_rate | int | No | Specifies the bitrate of the audio in kbps. A higher bitrate results in better audio quality and a larger file size. This parameter is available only when the audio format ( Default value: 128. Valid range: [6, 510]. |
API reference
Session (RealtimeSession)
A real-time speech synthesis session is created with client.audio.realtime.connect(model=...). The connection is established automatically when entering the with context (or manually by calling the session's connect() method).
| Method signature | Server response events (delivered via events() iteration) | Description |
|---|---|---|
session.createdSession createdsession.updated Session configuration updated | Connect to the server. Automatically called when entering the with context. | |
session.updatedSession configuration updated | Update default session configurations. For parameter details, see the Request parameters.After connecting, the server returns default input and output configurations. Call this method immediately after connecting to update these defaults.The server validates parameters when it receives a session.update event. If validation fails, it returns an error; otherwise, it updates the session configuration. | |
| None | Send a raw event. Text input is handled through the input_text_buffer family of events: append text chunks to the cloud input text buffer ({"type": "input_text_buffer.append", "text": ...}). The buffer is temporary storage that you can write to and commit later.
| |
input_text_buffer.clearedClear text received by the server | Send the {"type": "input_text_buffer.clear"} event to delete the text in the current cloud buffer. | |
input_text_buffer.committedSubmit text and trigger speech synthesisresponse.output_item.added New output content addedresponse.content_part.added New content added to assistant messageresponse.audio.delta Incremental audio generated by the modelresponse.audio.done Audio generation completedresponse.content_part.done Streaming of audio content for assistant message completedresponse.output_item.done Streaming of entire output item for assistant message completedresponse.done Response completed | Send the {"type": "input_text_buffer.commit"} event to commit the text previously appended to the cloud buffer and synthesize it immediately. An error occurs if the input text buffer is empty.
| |
session.finishedResponse completed | Send the session.finish event to terminate the task. Then keep consuming events() until the session.finished event. | |
| None | Close the connection. Automatically called when exiting the with context. | |
| None | Get the session_id of the current task. | |
| None | Get the response_id of the most recent response. | |
| None | Get the delay before the first audio packet arrives. |
Event iteration (events())
The server returns response events and data to the client as events. Iterate the session's events() in a receiver thread to handle server events; iteration ends after the session.finished event. error events are raised as DashScopeError exceptions, which you can catch with try/except.
| Method | Parameters | Return value | Description |
|---|---|---|---|
event: Server response event (dict). | Iterator | Includes API call responses and model-generated text and audio. Iteration ends after the session.finished event. For details, see Server events. | |
event: Server response event (dict). | Event or None | Read one server event. Returns None after a normal close. |