Utilice el SDK de Python de DashScope para integrar la síntesis de voz en tiempo real de Qwen-Audio-TTS en su aplicación mediante modos sin streaming, streaming unidireccional o streaming bidireccional.
Endpoint de servicio
El endpoint de servicio del SDK está determinado por los parámetros workspace/region del constructor de Client (corresponden a las direcciones siguientes, que incluyen el WorkspaceId). Para cambiar a una región diferente, modifique los parámetros del constructor de Client por los valores de la región de destino.
- Singapore
- China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceReemplace {WorkspaceId} con su ID de espacio de trabajo real.Recurso principal (client.audio.tts)
Ruta del recurso: client.audio.tts
Función: Síntesis de voz basada en WebSocket que ofrece tres modos de invocación: síntesis en una sola llamada (synthesize), síntesis por streaming (stream) y sesiones de streaming bidireccional (connect).
Puntos de entrada de invocación
synthesize() - sin streaming
Firma del método:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
text | str | Sí | El texto completo a sintetizar. Longitud máxima: 20,000 caracteres. |
bytes que contiene los datos de audio completos.
Descripción: Esta llamada bloqueante espera a que la síntesis se complete y devuelve los datos de audio completos de una sola vez. Es más adecuada para textos cortos donde no se requiere transmisión en tiempo real. Cada llamada a synthesize o stream crea su propia sesión; no es necesario reutilizar instancias.
stream() - streaming
Firma del método:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
text | str | Sí | El texto completo a sintetizar. Longitud máxima: 20,000 caracteres. |
Iterator[bytes] que contiene los datos de audio devueltos fragmento a fragmento.
Descripción: La síntesis por streaming envía el texto completo de una sola vez y devuelve el audio fragmento a fragmento (Iterator[bytes]). Es ideal para la síntesis de voz de texto corto que requiere baja latencia. Para enviar el texto en segmentos, utilice una sesión de streaming bidireccional (connect).
send_text() - entrada en streaming (método de sesión)
Envíe texto en segmentos dentro de una sesión de streaming bidireccional (client.audio.tts.connect(...)).
Firma del método:
text es el segmento de texto actual a sintetizar. Llame a send_text varias veces para agregar texto. Máximo por llamada: 20,000 caracteres. Máximo acumulado: 200,000 caracteres. El envío de texto y la recepción de audio deben ejecutarse de forma concurrente (utilícelo junto con audio_chunks()/events() y stop).
stop() - finalizar entrada en streaming (método de sesión)
Firma del método:
audio_chunks()/events() hasta que se sintetice el texto restante y se devuelvan todos los datos de audio. Si no se llama a este método, es posible que el texto final no se convierta en voz.
cancel() - cancelar síntesis por streaming (método de sesión)
Firma del método:
Métricas y respuestas de la sesión (atributos de sesión)
first_package_delay:float, el retraso en milisegundos desde el envío del texto hasta la recepción del primer fragmento de audio. Léalo después de que se complete la síntesis.usage:dict, la información de uso de la tarea de síntesis más reciente.last_response:dict, el mensaje de respuesta de la tarea de síntesis más reciente (con las clavesheader/payload). El ID de solicitud de la solicitud más reciente se puede recuperar delheaderdesession.last_response, lo que resulta útil para la solución de problemas y la correlación de registros.
Parámetros de solicitud
Los siguientes parámetros se configuran a través de los métodos synthesize/stream/connect de client.audio.tts para controlar el modelo, la voz, el formato y las características del audio de la síntesis (model, voice, format, sample_rate, volume, rate, pitch, language_hints y enable_ssml son parámetros con nombre; los demás parámetros se pasan a través del diccionario parameters).
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
model | str | Sí | El nombre del modelo. |
voice | str | Sí | La voz utilizada para la síntesis de habla.
|
format | str | No | Formato de codificación de audio.Predeterminado: mp3.Admite mp3, wav, pcm y otros formatos; la frecuencia de muestreo se establece a través del parámetro sample_rate, con valor predeterminado de 22050. |
volume | int | No | El nivel de volumen.Valor predeterminado: 50.Valores válidos: [0, 100]. |
rate | float | No | La velocidad del habla.Valor predeterminado: 1.0.Valores válidos: [0.5, 2.0]. |
pitch | float | No | El tono.Valor predeterminado: 1.0.Valores válidos: [0.5, 2.0]. |
bit_rate | int | No | La tasa de bits de audio en kbps. Cuando el formato de audio es mp3 u opus, utilice bit_rate para ajustar la tasa de bits.Valor predeterminado: 32.Valores válidos: [6, 510].Configure bit_rate a través del diccionario parameters: |
word_timestamp_enabled | bool | No | Especifica si se deben habilitar las marcas de tiempo a nivel de palabra.Valor predeterminado: false.Disponible solo en modo de salida por streaming. Se admiten voces clonadas. Para voces del sistema compatibles, consulte la lista de voces de Qwen-Audio-TTS.Configure word_timestamp_enabled a través del diccionario parameters: |
seed | int | No | Una semilla aleatoria para controlar la variación en la salida de la síntesis. Cuando la versión del modelo, el texto, la voz y otros parámetros no cambian, usar la misma semilla produce resultados idénticos.Valor predeterminado: 0.Valores válidos: [0, 65535]. |
language_hints | list[str] | No | Especifica el idioma objetivo para la síntesis de voz con el fin de mejorar la calidad de salida.Cuando la pronunciación de dígitos, la expansión de abreviaturas, la lectura de símbolos o la síntesis en idiomas minoritarios no cumpla con las expectativas, utilice este parámetro. Por ejemplo:
Valores válidos
|
instruction | str | No | Controla las características de la síntesis, como el dialecto, la emoción o el estilo de habla.Para detalles de uso, consulte Control de instrucciones. |
enable_aigc_tag | bool | No | Especifica si se debe incrustar una marca de agua AIGC en el audio generado. Cuando se establece en true, la marca de agua se incrusta en archivos de audio de formatos compatibles (wav/mp3/opus).Valor predeterminado: false.Configure enable_aigc_tag, aigc_propagator y aigc_propagate_id a través del diccionario parameters: |
aigc_propagator | str | No | Establece el campo ContentPropagator en la marca de agua AIGC, identificando al propagador del contenido. Surte efecto solo cuando enable_aigc_tag es true.Valor predeterminado: UID de Alibaba Cloud.Se configura a través del diccionario parameters. Consulte el ejemplo de enable_aigc_tag. |
aigc_propagate_id | str | No | Establece el campo PropagateID en la marca de agua AIGC, identificando de manera única una acción de propagación específica. Surte efecto solo cuando enable_aigc_tag es true.Valor predeterminado: El ID de solicitud de la solicitud actual de síntesis de voz.Se configura a través del diccionario parameters. Consulte el ejemplo de enable_aigc_tag. |
hot_fix | dict | No | Configura correcciones de pronunciación y reemplazos de texto aplicados antes de la síntesis.Parámetros:
|
Sesiones e iteración de eventos
La síntesis por streaming ya no utiliza interfaces de devolución de llamada: el audio y los eventos del servidor se reciben a través de los métodos de iteración de la sesión. stream()/synthesize() no requieren gestión de sesiones. El ciclo de vida de una sesión de streaming bidireccional (client.audio.tts.connect(...)) es: al entrar en el contexto with se abre la conexión automáticamente → múltiples llamadas a send_text() → stop() → leer todos los resultados restantes → al salir del contexto se cierra la conexión automáticamente.
audio_chunks() - iterar datos de audio
Firma del método:
Iterator[bytes] que contiene los fragmentos de datos binarios de audio devueltos uno a uno, en el formato especificado por el parámetro format.
Descripción: Itere en el hilo receptor para recibir los datos de audio fragmento a fragmento; se producen múltiples fragmentos durante la síntesis. Escriba los datos en un archivo o envíelos a un dispositivo de reproducción. Solo se permite un lector de events() o audio_chunks() por sesión.
events() - iterar eventos del servidor
Firma del método:
dict, que contienen header (información de la solicitud) y payload (información de salida)) como bytes de audio. payload.output contiene el tipo de evento, el texto original y otros detalles. Consulte campo output en eventos de events().
Descripción: Itere las respuestas del servidor en el hilo receptor. Contiene la información de salida de los eventos de síntesis (tipo de evento, texto original, información de la oración); acceda directamente a payload.output para obtener más detalles.
Manejo de errores
Cuando ocurre un error durante la síntesis, la capa WebSocket lanza una excepción DashScopeError y la conexión se cierra automáticamente después de que se lanza la excepción. Utilice try/except en el lado de envío o recepción para capturar y registrar errores para la solución de problemas:
Ciclo de vida de la sesión
- Al entrar en el contexto
withse abre la conexión automáticamente (inicialice de antemano los flujos de salida de audio o abra los recursos de archivos). - Después de que todo el texto se haya sintetizado y se hayan producido todos los datos de audio, la iteración
events()/audio_chunks()finaliza; a continuación se pueden leer métricas de rendimiento comofirst_package_delay. - Al salir del contexto
withse cierra la conexión automáticamente (libere después los recursos, como los dispositivos de reproducción de audio).
campo output en eventos de events()
El evento dict devuelto por la iteración events() de la sesión contiene un campo payload.output con información del evento de síntesis. Utilice este campo para rastrear el progreso de la síntesis y recuperar detalles por oración. La estructura del campo output es la siguiente:
| Campo | Tipo | Descripción |
|---|---|---|
type | str | Tipo de evento. Valores: sentence-begin (inicio de síntesis de oración), sentence-synthesis (síntesis de oración en curso) o sentence-end (finalización de síntesis de oración). |
original_text | str | El texto original de la oración actual. Se devuelve en los eventos sentence-begin y sentence-end. |
sentence | dict | Información de la oración. Contiene index (número de secuencia de la oración) y words (lista de palabras con información de marcas de tiempo cuando word_timestamp_enabled está activado). |
Ejemplos de código
El SDK admite los siguientes modos de síntesis:
- No streaming: Una llamada bloqueante que envía el texto completo de una sola vez y devuelve el audio completo directamente. Ideal para la síntesis de voz de texto corto.
- Streaming unidireccional: Una llamada no bloqueante que envía el texto completo de una sola vez y recibe los datos de audio iterando los fragmentos devueltos por
stream. Ideal para la síntesis de voz de texto corto que requiere baja latencia. - Streaming bidireccional: Una llamada no bloqueante que envía texto en múltiples segmentos y recibe el flujo de audio sintetizado incrementalmente en tiempo real iterando
audio_chunks()/events()de la sesión. Ideal para la síntesis de voz de texto largo que requiere baja latencia.
- Sin streaming
- Streaming unidireccional
- Streaming bidireccional
El texto enviado en una sola llamada no debe exceder los 20,000 caracteres. Superar este límite provoca un error.
- CLI de dashscope
Llamada a través de la línea de comandos dashscope.Para la tabla completa de regiones, consulte Resumen de URL base.