Referência de eventos do cliente CosyVoice: campos de run-task, continue-task e finish-task, ordem de envio e eventos correspondentes do servidor.
Fluxo de eventos
- Envie run-task para iniciar e configurar a tarefa e aguarde task-started.
- Após receber
task-started, envie texto por continue-task enquanto recebe eventos result-generated e o áudio sintetizado. - Após enviar todo o texto, envie finish-task e continue recebendo os resultados e o áudio restantes até chegar task-finished. Uma tarefa com falha retorna task-failed.
result-generated retorna metadados da frase. O áudio é transmitido separadamente por quadros binários no WebSocket ou por uma Audio Track no AOQ. Para conexão, autenticação e transporte de áudio, consulte a API WebSocket ou o acesso AOQ.
run-task
Imediatamente após estabelecer a conexão, o cliente envia run-task para iniciar a tarefa de síntese de fala e definir o modelo, a voz, a taxa de amostragem e os demais parâmetros.
headerobjectObrigatórioactionstringObrigatórioTipo de comando. Defina como
run-task.task_idstringObrigatórioID de tarefa gerado pelo cliente no formato UUID. Este ID correlaciona eventos subsequentes e deve corresponder ao
task_id nos comandos continue-task e finish-task.streamingstringObrigatórioDefina como
duplex.payloadobjectObrigatóriotask_groupstringObrigatórioGrupo de tarefas. Defina como
audio.taskstringObrigatórioTipo de tarefa. Defina como
tts.functionstringObrigatórioTipo de função. Defina como
SpeechSynthesizer.modelstringObrigatórioO nome do modelo.
parametersobjectObrigatórioParâmetros de síntese de fala.
text_typestringObrigatórioDefina como
PlainText.voicestringObrigatórioVoz usada na síntese de fala.
- Vozes do sistema: Consulte CosyVoice Voice list
- Vozes clonadas: Vozes personalizadas criadas por clonagem de voz
- Vozes personalizadas: Vozes personalizadas criadas por design de voz
formatstringOpcionalFormato de codificação de áudio.Valores válidos:
pcmwavmp3(padrão)opus
sample_rateintegerOpcionalTaxa de amostragem de áudio em Hz.Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100, 48000.
volumeintegerOpcionalNível de volume.Valor padrão: 50.Valores válidos: [0, 100].
ratefloatOpcionalVelocidade da fala.Valor padrão: 1,0.Valores válidos: [0,5, 2,0].
pitchfloatOpcionalTom da voz.Valor padrão: 1,0.Valores válidos: [0,5, 2,0].
bit_rateintegerOpcionalTaxa de bits de áudio em kbps. Se o formato de áudio for
mp3 ou opus, use bit_rate para ajustar a taxa de bits.Valor padrão: 32.Valores válidos: [6, 510].enable_ssmlbooleanOpcionalDefine se o SSML deve ser ativado.Valor padrão: Para restrições de uso do SSML (modelos, vozes e APIs compatíveis), consulte Limitations.
false.Se definido como
true, apenas um comando continue-task é permitido.word_timestamp_enabledbooleanOpcionalDefine se os carimbos de data/hora no nível de palavra devem ser ativados.Valor padrão:
false.Disponível apenas no modo de saída streaming. Vozes compatíveis: 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 compatíveis em CosyVoice Voice list. Vozes clonadas de outros modelos não oferecem suporte a este recurso.
seedintegerOpcionalSemente aleatória para controlar a variação na saída da síntese. Se a versão do modelo, o texto, a voz e outros parâmetros permanecerem inalterados, usar a mesma semente produz resultados idênticos.Valor padrão: 0.Valores válidos: [0, 65535].
language_hintsarray[string]Opcional- Este parâmetro é um array, mas a versão atual processa apenas o primeiro elemento. Passe um único valor.
- Este parâmetro especifica o idioma de destino para a síntese de fala. Ele não está relacionado ao idioma da amostra de áudio usada na clonagem de voz. Para definir o idioma de origem de uma tarefa de clonagem, consulte a referência da API de clonagem de voz.
- Pronúncia inesperada de dígitos: "olá, isto é 110" é lido como "olá, isto é um zero" em vez da pronúncia chinesa esperada
- Pronúncia imprecisa de símbolos: "@" é lido como o equivalente chinês em vez de "at"
- Baixa qualidade na síntese de idiomas minoritários com resultados pouco naturais
Valores válidos
Valores válidos
zh: Chinêsen: Inglêsfr: Francêsde: Alemãoja: Japonêsko: Coreanoru: Russopt: Portuguêsth: Tailandêsid: Indonésiovi: Vietnamitaes: Espanholit: Italianoms: Malaiofil: Filipinoar: Árabe
instructionstringOpcionalDefine uma instrução para controlar dialeto, emoção ou características da voz durante a síntese. Para detalhes de uso, consulte Instruction control.
enable_aigc_tagbooleanOpcionalDefine se uma marca d'água AIGC deve ser incorporada ao áudio gerado. Se definido como
true, a marca d'água é incorporada em arquivos de áudio dos formatos compatíveis (wav/mp3/opus).Valor padrão: false.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 oferecem suporte a este recurso.
aigc_propagatorstringOpcionalDefine o campo
ContentPropagator na marca d'água AIGC, identificando o propagador do conteúdo. Tem efeito apenas quando enable_aigc_tag é true.Valor padrão: UID da Alibaba Cloud.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 oferecem suporte a este recurso.
aigc_propagate_idstringOpcionalDefine o campo
PropagateID na marca d'água AIGC, identificando exclusivamente uma ação de propagação específica. Tem efeito apenas quando enable_aigc_tag é true.Valor padrão: ID da solicitação atual de síntese de fala.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 oferecem suporte a este recurso.
hot_fixobjectOpcionalConfigura correções de pronúncia e substituições de texto aplicadas antes da síntese.Parâmetros:
This feature isn't supported by cosyvoice-v2.
pronunciation: Pronúncia personalizada. Especifica anotações pinyin para palavras a fim de corrigir pronúncias padrão imprecisas.replace: Substituição de texto. Substitui palavras especificadas pelo texto de destino antes da síntese. O texto substituído é usado como entrada real da síntese.
enable_markdown_filterbooleanOpcionalApenas vozes clonadas de cosyvoice-v3-flash oferecem suporte a este recurso.
false.Valores válidos:true: Ativar filtragem de Markdownfalse: Desativar filtragem de Markdown
inputobjectObrigatórioDefina como um objeto vazio
{}. Envie o texto para sintetizar por meio do comando continue-task.Solicitação:
Resposta:
continue-task
Após receber task-started, o cliente envia continue-task para fornecer o texto a sintetizar. O texto pode ser enviado de uma vez ou em segmentos sequenciais.
headerobjectObrigatórioactionstringObrigatórioTipo de comando. Defina como
continue-task.task_idstringObrigatórioID da tarefa no formato UUID. Deve corresponder ao
task_id em run-task.streamingstringObrigatórioDefina como
duplex.payloadobjectObrigatórioinputobjectObrigatórioContém o texto a ser sintetizado.
textstringObrigatórioTexto a ser sintetizado. Máximo de 20.000 caracteres por mensagem e 200.000 caracteres cumulativamente.
O intervalo de envio não deve exceder 23 segundos; caso contrário, a conexão atingirá o tempo limite.
Solicitação:
Resposta:
finish-task
Imediatamente após enviar todo o texto, o cliente envia finish-task para informar ao servidor que a entrada terminou e solicitar a conclusão da tarefa. Para cancelar o turno de síntese atual, defina directive como cancel em input.
headerobjectObrigatórioactionstringObrigatórioTipo de comando. Defina como
finish-task.task_idstringObrigatórioID da tarefa no formato UUID. Deve corresponder ao
task_id em run-task.streamingstringObrigatórioDefina como
duplex.payloadobjectObrigatórioinputobjectObrigatórioDefina como
{} para a conclusão normal da tarefa. Inclua directive para cancelar a rodada de síntese atual.directivestringOpcionalControla como a tarefa termina. Atualmente, apenas
cancel tem suporte. Se definido como cancel, a rodada de síntese atual é cancelada e o servidor retorna imediatamente um evento task-finished sem produzir mais áudio.Após o cancelamento, inicie uma nova tarefa de síntese na mesma conexão WebSocket enviando um novo evento run-task sem reconectar.- Conclusão normal
- Cancelar tarefa
Solicitação:
Resposta: