Use o SDK Node.js de voz para chamar Qwen-Audio-TTS com texto completo ou em streaming e processar áudio, timestamps de palavras e uso.
Instalar o SDK
Requer Node.js 18 ou posterior. Baixe o pacote SDK 0.1.0 e execute no projeto:
Início rápido
Obtenha uma chave de API no console e defina-a na variável de ambiente DASHSCOPE_API_KEY.
Salve o exemplo como example.mjs e execute node example.mjs.
Referência da API
Opções do construtor
Opções do construtor de SpeechSynthesizer:
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
apiKey | string | Não | Chave de API. Usa DASHSCOPE_API_KEY por padrão. |
workspaceId | string | Não | ID do espaço de trabalho. Usa DASHSCOPE_WORKSPACE_ID por padrão. |
baseUrl | string | Não | Defina o hostname como dashscope-intl.aliyuncs.com (Singapura). |
model | string | Não | ID do modelo. Padrão: qwen-audio-3.1-tts-flash. |
voice | string | Sim | ID da voz. Escolha uma voz compatível com o modelo. |
format | 'pcm' | 'wav' | 'mp3' | 'opus' | Não | Codificação de áudio. Usa o padrão do serviço se omitida. |
sampleRate | 8000 | 16000 | 22050 | 24000 | 44100 | 48000 | Não | Taxa de amostragem em Hz. Deve corresponder à codificação; o serviço define o valor se omitido. |
volume | number | Não | Volume: [0,100]. Padrão do serviço: 50. |
rate | number | Não | Velocidade da fala: [0.5,2.0]. Padrão do serviço: 1.0. |
pitch | number | Não | Tom: [0.5,2.0]. Padrão do serviço: 1.0. |
wordTimestampEnabled | boolean | Não | Retorna timestamps de palavras. Padrão: false. |
languageHints | string[] | Não | Dicas de idioma de destino. Apenas o primeiro elemento tem efeito. |
instruction | string | Não | Instruções de síntese para dialeto, emoção ou papel. |
parameters | TtsSynthesisParameters | Não | Parâmetros adicionais, como enable_ssml, seed e hot_fix. |
connectTimeoutMs | number | Não | Tempo limite de conexão em ms. Padrão: 10000. |
taskTimeoutMs | number | Não | Tempo limite da confirmação de início/fim em ms. Padrão: 60000; 0 desativa. |
parameters.enable_ssml | boolean | Não | Ativa SSML. Envie o texto SSML completo e não vazio uma vez por tarefa. Consulte os limites. |
parameters.bit_rate | number | Não | Taxa de bits MP3/Opus em kbps. Intervalo: [6,510]; padrão: 32. |
parameters.seed | number | Não | Semente aleatória: [0,65535]. |
parameters.hot_fix | Record<string, unknown> | Não | Configuração de hot-fix em parameters.hot_fix. Consulte a estrutura em eventos do cliente. |
Métodos principais
| Método | Retorno | Descrição |
|---|---|---|
synthesize(text: string) | Promise<Buffer> | Sintetiza o texto completo e retorna áudio. Até 20000 caracteres. |
begin() | Promise<void> | Inicia a síntese em streaming; depois envie texto. |
sendText(text: string) | void | Envia texto: até 20000 caracteres por chamada e 200000 por tarefa. |
end() | Promise<Buffer> | Encerra a entrada, aguarda a síntese e retorna o áudio completo. |
cancel() | void | Solicita o cancelamento da síntese. |
close(code?: number, reason?: string) | void | Fecha a conexão e libera os recursos da tarefa. |
Eventos de callback
Registre callbacks com on(event, listener). Consulte os campos completos em eventos do servidor.
| Evento | Payload | Descrição |
|---|---|---|
started | { taskId: string } | A tarefa iniciou e aceita entrada. |
audio | Buffer | Trecho binário de áudio; pode ocorrer várias vezes. |
sentenceBegin | { index: number; text: string } | A síntese de uma frase começou. |
sentenceEnd | { index: number; text: string; characters?: number; words?: TtsWord[]; usage?: TtsUsage } | Síntese da frase concluída; pode incluir timestamps e uso original. |
finished | { taskId: string; characters?: number; usage?: TtsUsage } | A tarefa terminou e o estado local foi limpo. |
failed / error | DashScopeError | Erro com code, message e identificadores da requisição. |
close | { code: number; reason: string } | Notificação de fechamento da conexão subjacente. |
event | ServerEvent | Mensagem JSON original do serviço. |