Todos los productos
Search
Centro de documentos

Alibaba Cloud Model Studio:SDK de Python

Última actualización: Oct 12, 2026

Este tema describe las interfaces clave y los parámetros de solicitud para llamar a la síntesis de voz en tiempo real (Qwen) con DashScope Python SDK.

Guía del usuario: Para introducciones a los modelos y recomendaciones de selección, consulte Síntesis de voz en tiempo real – Qwen o Síntesis de voz – Qwen.

Requisitos previos

Requiere DashScope Python SDK 1.25.11 o posterior.

Introducción

import os
import base64
import threading
import time
import dashscope
from dashscope.audio.qwen_tts_realtime import *

qwen_tts_realtime: QwenTtsRealtime = None
text_to_synthesize = [
    'Right? I love supermarkets like this.',
    'Especially during Chinese New Year,',
    'I go shopping at supermarkets.',
    'And I feel',
    'absolutely thrilled!',
    'I want to buy so many things!'
]

DO_VIDEO_TEST = False

def init_dashscope_api_key():
    """
        Set your DashScope API key. More information:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    # API keys differ between the Singapore and Beijing regions. Get an API key: https://www.alibabacloud.com/help/model-studio/get-api-key
    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # Load API key from environment variable DASHSCOPE_API_KEY
    else:
        dashscope.api_key = 'your-dashscope-api-key'  # Set API key manually

class MyCallback(QwenTtsRealtimeCallback):
    def __init__(self):
        self.complete_event = threading.Event()
        self.file = open('result_24k.pcm', 'wb')

    def on_open(self) -> None:
        print('connection opened, init player')

    def on_close(self, close_status_code, close_msg) -> None:
        self.file.close()
        print('connection closed with code: {}, msg: {}, destroy player'.format(close_status_code, close_msg))

    def on_event(self, response: str) -> None:
        try:
            global qwen_tts_realtime
            type = response['type']
            if 'session.created' == type:
                print('start session: {}'.format(response['session']['id']))
            if 'response.audio.delta' == type:
                recv_audio_b64 = response['delta']
                self.file.write(base64.b64decode(recv_audio_b64))
            if 'response.done' == type:
                print(f'response {qwen_tts_realtime.get_last_response_id()} done')
            if 'session.finished' == type:
                print('session finished')
                self.complete_event.set()
        except Exception as e:
            print('[Error] {}'.format(e))
            return

    def wait_for_finished(self):
        self.complete_event.wait()

if __name__  == '__main__':
    init_dashscope_api_key()

    print('Initializing ...')

    callback = MyCallback()

    qwen_tts_realtime = QwenTtsRealtime(
        # To use instruction control, replace the model with qwen3.5-omni-plus-realtime
        model='qwen3-tts-flash-realtime',
        callback=callback,
        # Singapore region
        url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime'
        )

    qwen_tts_realtime.connect()
    qwen_tts_realtime.update_session(
        voice = 'Cherry',
        response_format = AudioFormat.PCM_24000HZ_MONO_16BIT,
        # To use instruction control, uncomment the following lines and replace the model with qwen3.5-omni-plus-realtime
        # instructions='Speak quickly with a rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True,
        mode = 'server_commit'
    )
    for text_chunk in text_to_synthesize:
        print(f'send text: {text_chunk}')
        qwen_tts_realtime.append_text(text_chunk)
        time.sleep(0.1)
    qwen_tts_realtime.finish()
    callback.wait_for_finished()
    print('[Metric] session: {}, first audio delay: {}'.format(
                    qwen_tts_realtime.get_session_id(),
                    qwen_tts_realtime.get_first_audio_delay(),
                    ))
import base64
import os
import threading
import dashscope
from dashscope.audio.qwen_tts_realtime import *

qwen_tts_realtime: QwenTtsRealtime = None
text_to_synthesize = [
    'This is the first sentence.',
    'This is the second sentence.',
    'This is the third sentence.',
]

DO_VIDEO_TEST = False

def init_dashscope_api_key():
    """
        Set your DashScope API key. More information:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    # API keys differ between the Singapore and Beijing regions. Get an API key: https://www.alibabacloud.com/help/model-studio/get-api-key
    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # Load API key from environment variable DASHSCOPE_API_KEY
    else:
        dashscope.api_key = 'your-dashscope-api-key'  # Set API key manually

class MyCallback(QwenTtsRealtimeCallback):
    def __init__(self):
        super().__init__()
        self.response_counter = 0
        self.complete_event = threading.Event()
        self.file = open(f'result_{self.response_counter}_24k.pcm', 'wb')

    def reset_event(self):
        self.response_counter += 1
        self.file = open(f'result_{self.response_counter}_24k.pcm', 'wb')
        self.complete_event = threading.Event()

    def on_open(self) -> None:
        print('connection opened, init player')

    def on_close(self, close_status_code, close_msg) -> None:
        print('connection closed with code: {}, msg: {}, destroy player'.format(close_status_code, close_msg))

    def on_event(self, response: str) -> None:
        try:
            global qwen_tts_realtime
            type = response['type']
            if 'session.created' == type:
                print('start session: {}'.format(response['session']['id']))
            if 'response.audio.delta' == type:
                recv_audio_b64 = response['delta']
                self.file.write(base64.b64decode(recv_audio_b64))
            if 'response.done' == type:
                print(f'response {qwen_tts_realtime.get_last_response_id()} done')
                self.complete_event.set()
                self.file.close()
            if 'session.finished' == type:
                print('session finished')
                self.complete_event.set()
        except Exception as e:
            print('[Error] {}'.format(e))
            return

    def wait_for_response_done(self):
        self.complete_event.wait()

if __name__  == '__main__':
    init_dashscope_api_key()

    print('Initializing ...')

    callback = MyCallback()

    qwen_tts_realtime = QwenTtsRealtime(
        # To use instruction control, replace the model with qwen3.5-omni-plus-realtime
        model='qwen3-tts-flash-realtime',
        callback=callback,
        # Singapore region
        url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime'
        )

    qwen_tts_realtime.connect()
    qwen_tts_realtime.update_session(
        voice = 'Cherry',
        response_format = AudioFormat.PCM_24000HZ_MONO_16BIT,
        # To use instruction control, uncomment the following lines and replace the model with qwen3.5-omni-plus-realtime
        # instructions='Speak quickly with a rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True,
        mode = 'commit'
    )
    print(f'send text: {text_to_synthesize[0]}')
    qwen_tts_realtime.append_text(text_to_synthesize[0])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    callback.reset_event()

    print(f'send text: {text_to_synthesize[1]}')
    qwen_tts_realtime.append_text(text_to_synthesize[1])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    callback.reset_event()

    print(f'send text: {text_to_synthesize[2]}')
    qwen_tts_realtime.append_text(text_to_synthesize[2])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()

    qwen_tts_realtime.finish()
    print('[Metric] session: {}, first audio delay: {}'.format(
                    qwen_tts_realtime.get_session_id(),
                    qwen_tts_realtime.get_first_audio_delay(),
                    ))

Visite GitHub para descargar más código de muestra.

Parámetros de solicitud

Establezca estos parámetros en el constructor QwenTtsRealtime:

Parámetro

Tipo

Obligatorio

Descripción

model

str

Sí

Nombre del modelo (consulte Modelos compatibles).

url

str

Sí

China (Pekín): wss://dashscope.aliyuncs.com/api-ws/v1/realtime

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

Configure estos parámetros usando update_session:

Parámetro

Tipo

Obligatorio

Descripción

voice

str

Sí

La voz para la síntesis de voz. Para obtener más información, consulte Voces compatibles.

Se admiten voces del sistema y voces personalizadas:

  • Voces del sistema: Disponibles solo para las series de modelos Qwen3-TTS-Instruct-Flash-Realtime, Qwen3-TTS-Flash-Realtime y Qwen-TTS-Realtime. Para muestras de voz, consulte Voces compatibles.

  • Voces personalizadas

    • Voces personalizadas mediante la función Clonación de voz (Qwen): Disponible solo para la serie de modelos Qwen3-TTS-VC-Realtime.

    • Voces personalizadas mediante la función Diseño de voz (Qwen): Disponible solo para la serie de modelos Qwen3-TTS-VD-Realtime.

language_type

str

No

Especifica el idioma del audio sintetizado. El valor predeterminado es Auto.

  • Auto: Utilice este valor cuando el idioma del texto sea incierto o contenga varios idiomas. El modelo asocia automáticamente la pronunciación para diferentes segmentos de idioma en el texto, pero no puede garantizar una precisión perfecta.

  • Idioma específico: Utilice esta opción para texto en un solo idioma. Especificar un idioma mejora significativamente la calidad de la síntesis y generalmente produce mejores resultados que Auto. Los valores válidos incluyen los siguientes:

    • Chinese

    • English

    • German

    • Italian

    • Portuguese

    • Spanish

    • Japanese

    • Korean

    • French

    • Russian

mode

str

No

El modo de interacción. Valores válidos:

  • server_commit (predeterminado): El servidor determina automáticamente cuándo sintetizar la voz, equilibrando latencia y calidad. Este modo se recomienda para la mayoría de los escenarios.

  • commit: El cliente activa manualmente la síntesis. Este modo tiene la latencia más baja, pero usted debe gestionar la integridad de las oraciones por su cuenta.

format

str

No

El formato de la salida de audio del modelo.

Formatos admitidos:

  • pcm (predeterminado)

  • wav

  • mp3

  • opus

Qwen-TTS-Realtime (consulte Modelos compatibles) solo admite pcm.

sample_rate

int

No

La frecuencia de muestreo de la salida de audio del modelo, en Hz.

Frecuencias de muestreo admitidas:

  • 8000

  • 16000

  • 24000 (predeterminado)

  • 48000

Qwen-TTS-Realtime (consulte Modelos compatibles) solo admite 24000.

speech_rate

float

No

La velocidad de habla del audio. Un valor de 1.0 es la velocidad normal. Un valor menor que 1.0 es más lento y un valor mayor que 1.0 es más rápido.

Valor predeterminado: 1.0.

Rango válido: [0.5, 2.0].

Qwen-TTS-Realtime (consulte Modelos compatibles) no admite este parámetro.

volume

int

No

El volumen del audio.

Valor predeterminado: 50.

Rango válido: [0, 100].

Qwen-TTS-Realtime (consulte Modelos compatibles) no admite este parámetro.

pitch_rate

float

No

El tono del audio sintetizado.

Valor predeterminado: 1.0.

Rango válido: [0.5, 2.0].

Qwen-TTS-Realtime (consulte Modelos compatibles) no admite este parámetro.

bit_rate

int

No

Especifica la tasa de bits del audio en kbps. Una tasa de bits más alta resulta en una mejor calidad de audio y un tamaño de archivo mayor. Este parámetro está disponible solo cuando el formato de audio (response_format) se establece en opus.

Valor predeterminado: 128.

Rango válido: [6, 510].

Qwen-TTS-Realtime (consulte Modelos compatibles) no admite este parámetro.

instructions

str

No

Establece las instrucciones. Para obtener más información, consulte Síntesis de voz en tiempo real - Qwen.

Valor predeterminado: None. El parámetro no está activo si no se establece.

Límite de longitud: La longitud no puede exceder 1600 tokens.

Idiomas admitidos: solo chino e inglés.

Alcance: Esta función está disponible solo para la serie de modelos Qwen3-TTS-Instruct-Flash-Realtime.

optimize_instructions

bool

No

Especifica si se deben optimizar las instructions para mejorar la naturalidad y la expresividad de la síntesis de voz.

Valor predeterminado: False

Comportamiento: Cuando se establece en True, el sistema mejora y reescribe semánticamente las instructions para generar instrucciones internas optimizadas para la síntesis de voz.

Escenarios: Recomendado para escenarios que requieren una expresión de voz detallada y de alta calidad.

Dependencia: Este parámetro depende de que se establezca el parámetro instructions. Si instructions está vacío, este parámetro no tiene efecto.

Alcance: Esta función está disponible solo para la serie de modelos Qwen3-TTS-Instruct-Flash-Realtime.

Interfaces clave

Clase QwenTtsRealtime

Importación: from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime

Firma del método

Eventos de respuesta del servidor (entregados mediante callback)

Descripción

def connect(self) -> None

session.created

Sesión creada

session.updated

Configuración de sesión actualizada

Conectarse al servidor.

    def update_session(self,
                       voice: str,
                       response_format: AudioFormat = AudioFormat.
                       PCM_24000HZ_MONO_16BIT,
                       mode: str = 'server_commit',
                       language_type : str = "Chinese",
                       **kwargs) -> None

session.updated

Configuración de sesión actualizada

Actualizar configuraciones de sesión predeterminadas. Para detalles de los parámetros, consulte Parámetros de solicitud.

Después de conectarse, el servidor devuelve configuraciones de entrada y salida predeterminadas. Llame a este método inmediatamente después de conectarse para actualizar estos valores predeterminados.

El servidor valida los parámetros cuando recibe un evento session.update. Si la validación falla, devuelve un error; de lo contrario, actualiza la configuración de la sesión.

def append_text(self, text: str) -> None

None

Agregar un fragmento de texto al búfer de entrada de la nube (almacenamiento temporal para texto antes del envío).

  • En el modo server_commit, el servidor decide cuándo enviar y sintetizar el texto en el búfer.
  • En el modo commit, el cliente debe activar la síntesis llamando a commit.
def clear_appended_text(self, ) -> None

input_text_buffer.cleared

Borrar texto recibido por el servidor

Eliminar todo el texto en el búfer de la nube.

def commit(self, ) -> None

input_text_buffer.committed

Enviar texto y activar la síntesis de voz

response.output_item.added

Nuevo contenido de salida agregado

response.content_part.added

Nuevo contenido agregado al mensaje del asistente

response.audio.delta

Audio incremental generado por el modelo

response.audio.done

Generación de audio completada

response.content_part.done

Transmisión de contenido de audio para mensaje del asistente completada

response.output_item.done

Transmisión de elemento de salida completo para mensaje del asistente completada

response.done

Respuesta completada

Enviar todo el texto en el búfer de la nube y sintetizar inmediatamente. Devuelve un error si el búfer está vacío.

  • En el modo server_commit, los clientes no necesitan enviar este evento. El servidor envía el búfer automáticamente.
  • En el modo de confirmación, los clientes deben llamar a commit para activar la síntesis de voz.
def finish(self, ) -> None

session.finished

Respuesta completada

Finalizar la tarea.

def close(self, ) -> None

None

Cerrar la conexión.

def get_session_id(self) -> str

None

Obtener el ID de sesión para la tarea actual.

def get_last_response_id(self) -> str

None

Obtener el ID de respuesta de la respuesta más reciente.

def get_first_audio_delay(self)

None

Obtener el retraso antes de que llegue el primer paquete de audio.

Interfaz de callback (QwenTtsRealtimeCallback)

El servidor envía respuestas y datos a través de callbacks. Implemente métodos de callback para gestionarlos.

Importación: from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback

Método

Parámetros

Valor de retorno

Descripción

def on_open(self) -> None

None

None

Se llama cuando se establece la conexión con el servidor.

def on_event(self, message: str) -> None

message: Evento de respuesta del servidor.

None

Incluye respuestas a llamadas de API, texto generado por el modelo y audio. Consulte Eventos del servidor.

def on_close(self, close_status_code, close_msg) -> None

close_status_code: Código de estado de cierre de WebSocket.

close_msg: Mensaje de cierre de WebSocket.

None

Llamado después de que el servidor cierra la conexión.