Utilize o DashScope Python SDK para integrar a síntese de fala em tempo real do CosyVoice à sua aplicação por meio dos modos sem streaming, streaming unidirecional ou streaming bidirecional.
Endpoint do service
O endpoint do SDK é determinado pelos parâmetros workspace e region do construtor do Client (correspondem aos endereços abaixo, que incluem o WorkspaceId). Para alternar para outra região, altere os parâmetros de construção do Client para os valores da região desejada.
- Singapore
- China (Beijing)
- CLI dashscope
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceSubstitua {WorkspaceId} pelo seu ID do workspace real.Recurso principal (client.audio.tts)
Caminho do recurso: client.audio.tts
Função: síntese de fala baseada em WebSocket, com três formas de chamada: síntese em uma etapa (synthesize), síntese em streaming (stream) e sessão com streaming bidirecional (connect).
Ponto de entrada de chamada
synthesize() - sem streaming
Assinatura do método:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | str | Sim | O texto completo a ser sintetizado. Comprimento máximo: 20.000 caracteres. |
bytes, todos os dados de áudio.
Descrição: chamada sem streaming, bloqueia e retorna todos os dados de áudio de uma só vez. Adequada para textos curtos sem requisitos estritos de tempo real. synthesize e stream criam a própria sessão a cada chamada; não é necessário reutilizar instâncias.
stream() - com streaming
Assinatura do método:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text | str | Sim | O texto completo a ser sintetizado. Comprimento máximo: 20.000 caracteres. |
Iterator[bytes], dados de áudio produzidos bloco a bloco.
Descrição: síntese em streaming que envia o texto completo de uma só vez e produz o áudio bloco a bloco (Iterator[bytes]). Adequada para cenários de síntese de fala de textos curtos que exigem alta capacidade de resposta em tempo real. Para enviar o texto em segmentos, use a sessão com streaming bidirecional (connect).
send_text() - entrada em streaming (método da sessão)
Envia o texto em segmentos em uma sessão com streaming bidirecional (client.audio.tts.connect(...)).
Assinatura do método:
text é o segmento de texto atual a ser sintetizado. Chame send_text várias vezes para anexar texto; máximo por chamada: 20.000 caracteres, máximo cumulativo: 200.000 caracteres. O envio de texto e o recebimento de áudio devem ocorrer de forma concorrente (use em conjunto com audio_chunks()/events() e stop).
stop() - finalizar entrada em streaming (método da sessão)
Assinatura do método:
audio_chunks()/events() até que o texto restante seja sintetizado e todos os dados de áudio sejam retornados. A falha ao chamar este método pode resultar na não conversão do texto final em fala.
cancel() - cancelar síntese em streaming (método da sessão)
Assinatura do método:
Métricas e respostas da sessão (atributos da sessão)
first_package_delay:float, a latência em milissegundos entre o envio do texto e o recebimento do primeiro bloco de dados de áudio. Deve ser lido após a conclusão da síntese.usage:dict, informações de uso da tarefa de síntese mais recente.last_response:dict, mensagem de resposta da tarefa de síntese mais recente (com as chavesheader/payload). O request_id da solicitação mais recente pode ser obtido noheaderdesession.last_response, útil para solução de problemas e correlação de logs.
Parâmetros de solicitação
Os parâmetros a seguir são definidos por meio dos métodos synthesize/stream/connect de client.audio.tts, para controlar o modelo, a voz, o formato e as características do áudio (model, voice, format, sample_rate, volume, rate, pitch, language_hints e enable_ssml são parâmetros nomeados; os demais parâmetros são passados por meio do dicionário parameters).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | str | Sim | O nome do modelo. |
voice | str | Sim | A voz utilizada para a síntese de fala.
|
format | str | Não | Formato de codificação de áudio.Padrão: mp3.Suporta mp3, wav, pcm e outros formatos; a taxa de amostragem é definida pelo parâmetro sample_rate, com valor padrão de 22050. |
volume | int | Não | O nível de volume.Valor padrão: 50.Valores válidos: [0, 100]. |
rate | float | Não | A velocidade da fala.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
pitch | float | Não | O tom da voz.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
bit_rate | int | Não | A taxa de bits de áudio em kbps. Quando o formato de áudio for mp3 ou opus, utilize bit_rate para ajustar a taxa de bits.Valor padrão: 32.Valores válidos: [6, 510].Defina bit_rate por meio do dicionário parameters: |
word_timestamp_enabled | bool | Não | Especifica se os carimbos de data/hora no nível da palavra devem ser ativados.Valor padrão: false.Disponível apenas no modo de saída com streaming. Vozes suportadas: vozes clonadas de cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, além de vozes do sistema marcadas como suportadas em CosyVoice Voice list. Vozes clonadas de outros modelos não suportam este recurso.Defina word_timestamp_enabled por meio do dicionário parameters: |
seed | int | Não | Uma semente aleatória para controlar a variação na saída da síntese. Quando a versão do modelo, o texto, a voz e outros parâmetros permanecem inalterados, o uso da mesma semente produz resultados idênticos.Valor padrão: 0.Valores válidos: [0, 65535]. |
language_hints | list[str] | Não | Especifica o idioma alvo para a síntese de fala a fim de melhorar a qualidade da saída.Quando a pronúncia de dígitos, expansão de abreviações, leitura de símbolos ou síntese de idiomas minoritários não atender às expectativas, utilize este parâmetro. Por exemplo:
Valores válidos
|
instruction | str | Não | Controla características da síntese, como dialeto, emoção ou estilo de fala.Para detalhes de uso, consulte Instruction control. |
enable_aigc_tag | bool | Não | Especifica se uma marca d'água AIGC deve ser incorporada ao áudio gerado. Quando definido como true, a marca d'água é incorporada em arquivos de áudio de formatos suportados (wav/mp3/opus).Valor padrão: false. Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. enable_aigc_tag, aigc_propagator e aigc_propagate_id por meio do dicionário parameters: |
aigc_propagator | str | Não | Define o campo ContentPropagator na marca d'água AIGC, identificando o propagador do conteúdo. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: UID da Alibaba Cloud.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. parameters. Consulte o exemplo de enable_aigc_tag. |
aigc_propagate_id | str | Não | Define o campo PropagateID na marca d'água AIGC, identificando exclusivamente uma ação de propagação específica. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: O ID da solicitação de síntese de fala atual.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. parameters. Consulte o exemplo de enable_aigc_tag. |
hot_fix | dict | Não | Configura correções de pronúncia e substituições de texto aplicadas antes da síntese. This feature isn't supported by cosyvoice-v2.
|
enable_markdown_filter | bool | Não | Apenas vozes clonadas de cosyvoice-v3-flash suportam este recurso.
enable_markdown_filter por meio do dicionário parameters: |
Sessão e iteração de eventos
A síntese em streaming não usa mais interfaces de callback: o áudio e os eventos do servidor são recebidos por meio dos métodos de iteração da sessão. stream()/synthesize() não exigem gerenciamento de sessão; o ciclo de vida de uma sessão com streaming bidirecional (client.audio.tts.connect(...)) é: entrada no contexto with com conexão estabelecida automaticamente → múltiplas chamadas de send_text() → stop() → leitura de todos os resultados → saída do contexto com fechamento automático da conexão.
audio_chunks() - iterar dados de áudio
Assinatura do método:
Iterator[bytes], fragmentos de dados binários de áudio produzidos bloco a bloco, no formato especificado pelo parâmetro format.
Descrição: Itere na thread receptora para receber os dados de áudio bloco a bloco; durante a síntese, vários blocos são produzidos. Grave os dados em um arquivo ou envie-os a um dispositivo de reprodução. A mesma sessão permite apenas um leitor de events() ou audio_chunks().
events() - iterar eventos do servidor
Assinatura do método:
dict, contendo header (informações da solicitação) e payload (informações de saída)) e bytes de áudio. O campo payload.output contém o tipo de evento, o texto original e outros detalhes. Consulte campo output nas mensagens de events().
Descrição: Itere as respostas do servidor na thread receptora; elas contêm as informações de saída dos eventos de síntese (tipo de evento, texto original, informações da frase etc.). Acesse diretamente payload.output para obter detalhes.
Tratamento de erros
Quando ocorre um erro durante a síntese, a camada WebSocket lança uma exceção DashScopeError e a conexão é fechada automaticamente após a exceção ser lançada. Use try/except no envio/recebimento para capturar e registrar os erros para solução de problemas:
Ciclo de vida da sessão
- A conexão é estabelecida automaticamente na entrada do contexto
with(inicialize fluxos de saída de áudio ou abra recursos de arquivo antes disso). - Após todo o texto ser sintetizado e todos os dados de áudio serem produzidos, a iteração de
events()/audio_chunks()termina; depois disso é possível ler métricas de desempenho comofirst_package_delay. - A conexão é fechada automaticamente na saída do contexto
with(libere dispositivos de reprodução de áudio e outros recursos em seguida).
Campo output nas mensagens de events()
O evento dict produzido pela iteração de events() da sessão contém um campo payload.output com informações sobre o evento de síntese. Utilize este campo para acompanhar o progresso da síntese e recuperar detalhes por frase. A estrutura do campo output é a seguinte:
| Campo | Tipo | Descrição |
|---|---|---|
type | str | Tipo de evento. Valores: sentence-begin (síntese da frase iniciada), sentence-synthesis (síntese da frase em andamento) ou sentence-end (síntese da frase concluída). |
original_text | str | O texto original da frase atual. Retornado nos eventos sentence-begin e sentence-end. |
sentence | dict | Informações da frase. Contém index (número sequencial da frase) e words (lista de palavras com informações de carimbo de data/hora quando word_timestamp_enabled está ativado). |
Exemplos de código
O SDK fornece as interfaces principais da síntese de fala e suporta os seguintes modos de chamada:
- Sem streaming: uma chamada bloqueante que envia o texto completo de uma só vez e retorna o áudio integral diretamente. Mais adequado para síntese de fala de textos curtos.
- Streaming unidirecional: uma chamada não bloqueante que envia o texto completo de uma só vez e recebe os dados iterando os blocos de áudio retornados por
stream. Mais adequado para cenários de texto curto que exigem alta capacidade de resposta em tempo real. - Streaming bidirecional: uma chamada não bloqueante que envia texto em vários segmentos e recebe em tempo real o fluxo de áudio sintetizado incrementalmente por meio da iteração de
audio_chunks()/events()da sessão. Mais adequado para cenários de texto longo que exigem alta capacidade de resposta em tempo real.
- Sem streaming
- Streaming unidirecional
- Streaming bidirecional
O texto enviado em uma única chamada não deve exceder 20.000 caracteres. Exceder esse limite dispara uma exceção
DashScopeError.