Skip to main content

Eventos do cliente CosyVoice

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

  1. Envie run-task para iniciar e configurar a tarefa e aguarde task-started.
  2. Após receber task-started, envie texto por continue-task enquanto recebe eventos result-generated e o áudio sintetizado.
  3. 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.
Aguarde task-started antes de enviar continue-task. run-task apenas inicia e configura a tarefa. Envie o texto a sintetizar por continue-task.
headerobjectObrigatório
actionstringObrigatório
Tipo de comando. Defina como run-task.
task_idstringObrigatório
ID 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ório
Defina como duplex.
payloadobjectObrigatório
task_groupstringObrigatório
Grupo de tarefas. Defina como audio.
taskstringObrigatório
Tipo de tarefa. Defina como tts.
functionstringObrigatório
Tipo de função. Defina como SpeechSynthesizer.
modelstringObrigatório
O nome do modelo.
parametersobjectObrigatório
Parâmetros de síntese de fala.
text_typestringObrigatório
Defina como PlainText.
voicestringObrigatório
Voz 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
formatstringOpcional
Formato de codificação de áudio.Valores válidos:
  • pcm
  • wav
  • mp3 (padrão)
  • opus
sample_rateintegerOpcional
Taxa de amostragem de áudio em Hz.Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100, 48000.
volumeintegerOpcional
Nível de volume.Valor padrão: 50.Valores válidos: [0, 100].
ratefloatOpcional
Velocidade da fala.Valor padrão: 1,0.Valores válidos: [0,5, 2,0].
pitchfloatOpcional
Tom da voz.Valor padrão: 1,0.Valores válidos: [0,5, 2,0].
bit_rateintegerOpcional
Taxa 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_ssmlbooleanOpcional
Define se o SSML deve ser ativado.Valor padrão: false.
Se definido como true, apenas um comando continue-task é permitido.
Para restrições de uso do SSML (modelos, vozes e APIs compatíveis), consulte Limitations.
word_timestamp_enabledbooleanOpcional
Define 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.
seedintegerOpcional
Semente 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.
Especifica o idioma de destino para a síntese de fala a fim de melhorar a qualidade da saída.Use este parâmetro 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. Por exemplo:
  • 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
  • zh: Chinês
  • en: Inglês
  • fr: Francês
  • de: Alemão
  • ja: Japonês
  • ko: Coreano
  • ru: Russo
  • pt: Português
  • th: Tailandês
  • id: Indonésio
  • vi: Vietnamita
  • es: Espanhol
  • it: Italiano
  • ms: Malaio
  • fil: Filipino
  • ar: Árabe
instructionstringOpcional
Define 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_tagbooleanOpcional
Define 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_propagatorstringOpcional
Define 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_idstringOpcional
Define 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_fixobjectOpcional
Configura correções de pronúncia e substituições de texto aplicadas antes da síntese.
This feature isn't supported by cosyvoice-v2.
Parâmetros:
  • 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.
Este exemplo usa pinyin para indicar a pronúncia de uma palavra em chinês e substitui o texto antes da síntese.
{
  "hot_fix": {
    "pronunciation": [
      {
        "天气": "tian1 qi4"
      }
    ],
    "replace": [
      {
        "今天": "金天"
      }
    ]
  }
}
enable_markdown_filterbooleanOpcional
Apenas vozes clonadas de cosyvoice-v3-flash oferecem suporte a este recurso.
Define se a filtragem de Markdown deve ser ativada. Quando ativada, o sistema remove automaticamente os símbolos de marcação Markdown do texto de entrada antes da síntese, evitando que sejam lidos em voz alta.Valor padrão: false.Valores válidos:
  • true: Ativar filtragem de Markdown
  • false: Desativar filtragem de Markdown
inputobjectObrigatório
Defina como um objeto vazio {}. Envie o texto para sintetizar por meio do comando continue-task.
Solicitação:
{
  "header": {
    "action": "run-task",
    "task_id": "b6e6cdf6-e9fa-429c-b1c1-cd231977c918",
    "streaming": "duplex"
  },
  "payload": {
    "input": {},
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "cosyvoice-v3-plus",
    "parameters": {
      "text_type": "PlainText",
      "voice": "longanyang",
      "format": "mp3",
      "sample_rate": 22050
    }
  }
}
Resposta:
{
  "header": {
    "task_id": "b6e6cdf6-e9fa-429c-b1c1-cd231977c918",
    "task_uuid": "1dd2b10b644e45b798f58ef96405215e",
    "event": "task-started",
    "attributes": {}
  },
  "payload": {}
}

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ório
actionstringObrigatório
Tipo de comando. Defina como continue-task.
task_idstringObrigatório
ID da tarefa no formato UUID. Deve corresponder ao task_id em run-task.
streamingstringObrigatório
Defina como duplex.
payloadobjectObrigatório
inputobjectObrigatório
Contém o texto a ser sintetizado.
textstringObrigatório
Texto 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:
{
  "header": {
    "action": "continue-task",
    "task_id": "b6e6cdf6-e9fa-429c-b1c1-cd231977c918",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "text": "Welcome to the speech synthesis service."
    }
  }
}
Resposta:
{
  "header": {
    "task_id": "b6e6cdf6-e9fa-429c-b1c1-cd231977c918",
    "event": "result-generated",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {
      "sentence": {
        "index": 0,
        "words": []
      },
      "type": "sentence-begin",
      "original_text": "Welcome to the speech synthesis service.",
      "normalized_text": "Welcome to the speech synthesis service."
    }
  }
}

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.
Após enviar finish-task, continue recebendo os resultados e o áudio restantes até chegar task-finished. Ao cancelar a tarefa, o servidor interrompe a saída de áudio subsequente e retorna task-finished.
headerobjectObrigatório
actionstringObrigatório
Tipo de comando. Defina como finish-task.
task_idstringObrigatório
ID da tarefa no formato UUID. Deve corresponder ao task_id em run-task.
streamingstringObrigatório
Defina como duplex.
payloadobjectObrigatório
inputobjectObrigatório
Defina como {} para a conclusão normal da tarefa. Inclua directive para cancelar a rodada de síntese atual.
directivestringOpcional
Controla 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:
{
  "header": {
    "action": "finish-task",
    "task_id": "b6e6cdf6-e9fa-429c-b1c1-cd231977c918",
    "streaming": "duplex"
  },
  "payload": {
    "input": {}
  }
}
Resposta:
{
  "header": {
    "task_id": "b6e6cdf6-e9fa-429c-b1c1-cd231977c918",
    "event": "task-finished",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {},
    "usage": {
      "characters": 40
    }
  }
}