Utilice el SDK de Python de DashScope para integrar la síntesis de voz en tiempo real de CosyVoice en su aplicación mediante modos sin streaming, streaming unidireccional o streaming bidireccional.
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.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.
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 (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: |
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ón DashScopeError 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). |
Ejemplos de código
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.