SDK de Python

Este tema describe las interfaces clave y los parámetros de solicitud para llamar a los modelos de la serie Qwen-TTS-Realtime con DashScope Python SDK.

Requisitos previos

Requiere DashScope Python SDK 2.0.1 o posterior.

Introducción

import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

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!'
]

# Las API Key de las regiones de Singapur y Pekín son diferentes. Obtenga su API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# Si no se ha configurado la variable de entorno, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # La siguiente configuración corresponde a la región de Singapur. Sustituya {WorkspaceId} por el ID real de su espacio de trabajo. El valor de region varía según la región.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Hilo receptor: itera los eventos del servidor y escribe el audio en el archivo de forma incremental
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # Crea una sesión de síntesis de voz en tiempo real: al entrar en el contexto with se establece la conexión automáticamente
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='server_commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text_chunk in text_to_synthesize:
                print(f'send text: {text_chunk}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
                time.sleep(0.1)
            # Notifica al servidor que la entrada ha finalizado (en el modo server_commit el servidor decide cuándo sintetizar)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))

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

Parámetros de solicitud

Establezca estos parámetros en el método connect de client.audio.realtime:

Parámetro	Tipo	Obligatorio	Descripción
model	str	Sí	Nombre del modelo (consulte Modelos compatibles).
ws_url	str	No	Endpoint de la sesión. Si se omite, se deriva automáticamente de los parámetros de construcción `workspace`/`region` del Client (China (Pekín): `wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime`; Singapur: `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime`).

Configure estos parámetros mediante el método update_session de la sesión (los parámetros con nombre se pasan directamente y el resto se transfieren al objeto session del evento session.update):

Parámetro	Tipo	Obligatorio	Descripción
voice	str	Sí	La voz para la síntesis de voz. Para obtener más información, consulte Lista de voces de Qwen-TTS.
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.
response_format	str	No	El formato de la salida de audio del modelo. Formatos admitidos: `pcm` (predeterminado) `wav` `mp3` `opus`
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
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].
volume	int	No	El volumen del audio. Rango válido: [0, 100].
pitch_rate	float	No	El tono del audio sintetizado. Valor predeterminado: 1.0. Rango válido: [0.5, 2.0].
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].

Interfaces clave

Sesión (RealtimeSession)

Una sesión de síntesis de voz en tiempo real se crea mediante client.audio.realtime.connect(model=...). La conexión se establece automáticamente al entrar en el contexto with (también puede llamar manualmente al método connect() de la sesión).

Firma del método	Eventos de respuesta del servidor (entregados mediante la iteración de `events()`)	Descripción
`def connect(self) -> "RealtimeSession"`	session.created Sesión creada session.updated Configuración de sesión actualizada	Conectarse al servidor. Se llama automáticamente al entrar en el contexto `with`.
`def update_session(self, output_modalities: List[str], , voice: str = None, *kwargs) -> None`	session.updated Configuración de sesión actualizada	Actualizar las 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 send_event(self, event: Dict[str, Any]) -> None`	None	Enviar un evento sin procesar. La entrada de texto se realiza mediante la familia de eventos `input_text_buffer`: agregar un fragmento de texto al búfer de entrada de la nube (`{"type": "input_text_buffer.append", "text": ...}`). El búfer es un almacenamiento temporal para texto que se escribe y se envía más tarde. 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 enviar el evento `input_text_buffer.commit` para activar la síntesis de voz.
`def send_event(self, event: Dict[str, Any]) -> None`	input_text_buffer.cleared Borrar texto recibido por el servidor	Enviar el evento `{"type": "input_text_buffer.clear"}` para eliminar todo el texto del búfer de la nube.
`def send_event(self, event: Dict[str, Any]) -> 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 el evento `{"type": "input_text_buffer.commit"}` para enviar todo el texto agregado previamente al búfer de la nube y sintetizarlo 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 commit, los clientes deben activar la síntesis de voz mediante commit.
`def end_session(self) -> None`	session.finished Respuesta completada	Enviar el evento session.finish para finalizar la tarea. Después, siga consumiendo `events()` hasta el evento `session.finished`.
`def close(self, ) -> None`	None	Cerrar la conexión. Se llama automáticamente al salir del contexto `with`.
`session.session_id`	None	Obtener el ID de sesión para la tarea actual.
`session.last_response_id`	None	Obtener el ID de respuesta de la respuesta más reciente.
`session.last_first_audio_delay`	None	Obtener el retraso antes de que llegue el primer paquete de audio.

Iteración de eventos (`events()`)

El servidor devuelve los eventos y datos de respuesta en forma de eventos. Itere el events() de la sesión en el hilo receptor para gestionar los eventos del servidor; la iteración finaliza después del evento session.finished. Los eventos error se lanzan como excepciones DashScopeError, que puede capturar con try/except.

Método	Parámetros	Valor de retorno	Descripción
`def events(self) -> Iterator[Dict]`	event: Evento de respuesta del servidor (`dict`).	Iterador	Incluye respuestas a llamadas de API, texto generado por el modelo y audio. La iteración finaliza después del evento `session.finished`. Para más información, consulte Eventos del servidor.
`def recv_event(self) -> Optional[Dict]`	event: Evento de respuesta del servidor (`dict`).	Evento o `None`	Leer un evento del servidor. Devuelve `None` tras un cierre normal.

​Requisitos previos

​Introducción

​Parámetros de solicitud

​Interfaces clave

​Sesión (RealtimeSession)