Requisitos previos
Qwen-Audio-TTS
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.CosyVoice
Endpoint de servicio
El endpoint del SDK viene determinado por los parámetros workspace y 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 esa región.
- Singapore
- China (Beijing)
- CLI de dashscope
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceReemplace {WorkspaceId} con su ID de espacio de trabajo real.Inicio rápido
Qwen-Audio-TTS
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.
CosyVoice
El SDK proporciona las interfaces clave para la síntesis de voz y admite los siguientes modos de llamada:
- Sin 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 iterando los fragmentos de audio entregados por
stream. Ideal para la síntesis de voz de texto corto que requiere un alto rendimiento en tiempo real. - Streaming bidireccional: Una llamada no bloqueante que envía texto en múltiples segmentos y recibe en tiempo real el flujo de audio sintetizado incrementalmente iterando los métodos
audio_chunks()/events()de la sesión. Ideal para la síntesis de voz de texto largo que requiere un alto rendimiento en tiempo real.
- 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 una excepción
DashScopeError.Parámetros de solicitud
Qwen-Audio-TTS
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 | Para las voces multilingües y dialectales de qwen-audio-3.1-tts-flash, este parámetro permite especificar el idioma o dialecto. Consulte la configuración de voces multilingües y dialectales para obtener más información.
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:
|
CosyVoice
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 (model, voice, format, sample_rate, volume, rate, pitch, language_hints y enable_ssml son parámetros con nombre; los parámetros restantes 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.Valor predeterminado: mp3.Admite mp3, wav, pcm y otros formatos. La tasa de muestreo se establece mediante el parámetro sample_rate, con un 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. Voces compatibles: voces clonadas de cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 y voces del sistema marcadas como compatibles en la lista de voces de CosyVoice. Las voces clonadas de otros modelos no admiten esta función.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. Solo cosyvoice-v3-flash, cosyvoice-v3-plus y cosyvoice-v2 admiten esta función. 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: Alibaba Cloud UID.Solo cosyvoice-v3-flash, cosyvoice-v3-plus y cosyvoice-v2 admiten esta función. 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.Solo cosyvoice-v3-flash, cosyvoice-v3-plus y cosyvoice-v2 admiten esta función. 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. Esta función no es compatible con cosyvoice-v2.
|
enable_markdown_filter | bool | No | Solo las voces clonadas de cosyvoice-v3-flash admiten esta función.
enable_markdown_filter a través del diccionario parameters: |
Referencia de la API
Qwen-Audio-TTS
Consulte la referencia actual de Qwen-Audio-TTS Python SDK.
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.
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ónDashScopeError 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). |
CosyVoice
Consulte la referencia actual de CosyVoice Python SDK.
Recurso principal (client.audio.tts)
Ruta del recurso: client.audio.tts
Descripción: Síntesis de voz basada en WebSocket, con tres modos de llamada: síntesis de una sola llamada (synthesize), síntesis por streaming (stream) y sesión de streaming bidireccional (connect).
Punto de entrada de llamada
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 y devuelve los datos de audio completos de una sola vez. Es más adecuada para textos cortos donde no se requiere un rendimiento estricto en tiempo real. synthesize y stream crean una nueva sesión en cada llamada; 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], los datos de audio entregados fragmento a fragmento.
Descripción: Síntesis por streaming que envía el texto completo de una sola vez y entrega el audio fragmento a fragmento (Iterator[bytes]). Es más adecuada para escenarios de síntesis de voz de texto corto que requieren un alto rendimiento en tiempo real. Para enviar texto en segmentos, utilice la sesión de streaming bidireccional (connect).
send_text() - entrada en streaming (método de sesión)
Envía 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 la 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 la 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 request_id de la solicitud más reciente se puede obtener delheaderdesession.last_response, lo que resulta útil para la solución de problemas y la correlación de registros.
Iteración de sesión y eventos
La síntesis por streaming ya no utiliza interfaces de devolución de llamada: el audio y los eventos del servidor se reciben mediante 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: entrar en el contexto with para establecer la conexión automáticamente → múltiples llamadas a send_text() → stop() → leer todos los resultados → salir del contexto para cerrar la conexión automáticamente.
audio_chunks() - iterar los datos de audio
Firma del método:Iterator[bytes], los datos binarios de audio entregados fragmento a fragmento, en el formato especificado por el parámetro format.
Descripción: Itere en el hilo de recepción para recibir los datos de audio fragmento a fragmento; durante la síntesis se entregan múltiples fragmentos. Escriba los datos en un archivo o envíelos a un dispositivo de reproducción. Una sesión solo permite un lector de events() o audio_chunks().
events() - iterar los 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. El campo payload.output contiene el tipo de evento, el texto original y otra información. Consulte campo output en los mensajes de events().
Descripción: Itere sobre las respuestas del servidor en el hilo de recepción. Las respuestas contienen la información de salida de los eventos de síntesis (tipo de evento, texto original, información de la oración, etc.); acceda a payload.output directamente para obtener más detalles.
Manejo de errores
Cuando se produce un error durante la síntesis, la capa WebSocket genera una excepciónDashScopeError y la conexión se cierra automáticamente después de que se genere la excepción. Utilice try/except en el lado de envío/recepción para capturar y registrar errores para la solución de problemas:
Ciclo de vida de la sesión
- La conexión se establece automáticamente al entrar en el contexto
with(puede inicializar flujos de salida de audio o abrir recursos de archivos con antelación). - Después de que todo el texto se sintetice y se hayan entregado todos los datos de audio, la iteración de
events()/audio_chunks()finaliza; después de eso, puede leer métricas de rendimiento comofirst_package_delay. - La conexión se cierra automáticamente al salir del contexto
with(puede liberar dispositivos de reproducción de audio y otros recursos posteriormente).
Campo output en los mensajes de events()
El dict de evento entregado por el iterador 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). |