Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Qwen-Audio-Realtime Node.js SDK

Última atualização: Nov 20, 2026

Use o SDK Node.js de voz para configurar sessões Qwen-Audio-Realtime, trocar áudio e processar transcrição e chamadas de funções.

Pré-requisitos

Obtenha uma chave de API no console e defina-a na variável de ambiente DASHSCOPE_API_KEY.

Instalar o SDK

Requer Node.js 18 ou posterior. Baixe o pacote SDK 0.1.0 e execute no projeto:

npm install ./dashscope-sdk-nodejs-0.1.0.tgz

Início rápido

Baixe o áudio de exemplo como input.mp3 e converta para PCM mono de 16 kHz e 16 bits:

ffmpeg -i input.mp3 -f s16le -ac 1 -ar 16000 input.pcm

Salve o exemplo como example.mjs e execute node example.mjs.

import { readFileSync, writeFileSync } from 'node:fs'
import { setTimeout as sleep } from 'node:timers/promises'
import { RealtimeClient } from 'dashscope-sdk-nodejs/realtime'

const pcm = readFileSync('input.pcm')
const client = new RealtimeClient({
  apiKey: process.env.DASHSCOPE_API_KEY,
  workspaceId: process.env.DASHSCOPE_WORKSPACE_ID,
  baseUrl: 'dashscope-intl.aliyuncs.com',
  model: 'qwen-audio-3.1-realtime-plus',
  voice: 'longanqian_v3.1',
  turnDetection: null,
  inputTranscription: { language: 'zh' },
})
const audio = []
function fail(err) {
  console.error(err.code, err.message)
  process.exitCode = 1
  client.close()
}
const timer = setTimeout(() => fail(new Error('Response timed out')), 60000)
client.on('close', () => clearTimeout(timer))
client.on('error', fail)
client.on('audio', chunk => audio.push(chunk))
client.on('inputTranscript', ({ transcript }) => console.log('User:', transcript))
client.on('outputTranscript', ({ transcript }) => console.log('Assistant:', transcript))
client.once('sessionUpdated', () => {
  ;(async () => {
    for (let offset = 0; offset < pcm.length; offset += 3200) {
      client.appendAudio(pcm.subarray(offset, offset + 3200))
      await sleep(100)
    }
    client.commit()
    client.createResponse()
  })().catch(fail)
})
client.once('responseDone', event => {
  if (event.response?.status !== 'completed') {
    fail(new Error('Response status: ' + event.response?.status))
    return
  }
  writeFileSync('output.pcm', Buffer.concat(audio))
  client.close()
})
try {
  await client.connect()
} catch (err) {
  fail(err)
}

Parâmetros da solicitação

Opções do construtor de RealtimeClient:

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

Sim

ID do modelo.

voice

string

Não

ID da voz. Usa a voz padrão do serviço se omitida.

instructions

string

Não

Instruções de sistema para papel, estilo e outros comportamentos.

turnDetection

TurnDetection | null

Não

Padrão: { type: "server_vad" }. null ativa o envio manual. Também aceita smart_turn e smart_turn_v2.

modalities

Array<'text' | 'audio'>

Não

Modalidades de saída. Padrão: ["text", "audio"].

maxHistoryTurns

number

Não

Turnos de histórico: [1,50]. Padrão do serviço: 20.

tools

ToolDefinition[]

Não

Definições de ferramentas. A aplicação executa as ferramentas e valida os argumentos.

inputTranscription

{ model?: string; language?: string } | null

Não

Configuração de transcrição de entrada, como { model: "fun-asr", language: "zh" }; null desativa.

sessionExtras

SessionConfig

Não

Configurações adicionais, como speech_rate e enable_search. Substituem as de nível superior correspondentes; consulte os campos em eventos do cliente.

connectTimeoutMs

number

Não

Tempo limite de conexão em ms. Padrão: 10000.

Referência da API

Métodos principais

Método

Retorno

Descrição

connect()

Promise<void>

Conecta e envia a configuração. sessionUpdated confirma a aplicação.

updateSession(session: SessionConfig)

void

Atualiza a sessão; confirme em sessionUpdated.

appendAudio(pcm: Buffer | Uint8Array)

void

Envia áudio PCM mono de 16 kHz e 16 bits.

commit()

void

Confirma o buffer no modo manual.

clearAudioBuffer()

void

Limpa o buffer ainda não confirmado.

createResponse(response?: Record<string, unknown>)

void

Solicita uma resposta do modelo.

cancelResponse()

void

Cancela a resposta atual mantendo a sessão.

createConversationItem(item: ConversationItem, previousItemId?: string)

void

Adiciona histórico ou resultados. previousItemId define a posição.

submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean)

void

Envia o resultado como string. autoCreateResponse é true por padrão e solicita a próxima resposta.

deleteConversationItem(itemId: string)

void

Exclui um item da conversa.

retrieveConversationItem(itemId: string)

void

Consulta um item; receba-o via event.

sendEvent(event: ClientEvent)

void

Envia um evento bruto do cliente.

close(code?: number, reason?: string)

void

Fecha a sessão e a conexão WebSocket.

Eventos de callback

Registre callbacks com on(event, listener). Consulte os campos completos em eventos do servidor.

Evento

Payload

Descrição

open

void

Conexão estabelecida e configuração inicial enviada.

sessionCreated / sessionUpdated

ServerEvent

Criação da sessão ou confirmação da configuração.

audio

Buffer

Trecho binário de áudio; pode ocorrer várias vezes.

audioTranscriptDelta

{ delta: string }

Texto incremental da transcrição do áudio de saída.

outputTranscript

{ transcript: string }

Transcrição completa do áudio de saída.

textDelta / textDone

{ delta: string } / { text: string }

Texto incremental ou completo na modalidade somente texto.

inputTranscriptDelta

{ text: string; stash: string }

text é texto confirmado e stash, provisório. Substitua a exibição pela combinação dos dois, sem concatenar aos anteriores.

inputTranscript

{ transcript: string }

Transcrição final do áudio de entrada.

speechStarted / speechStopped

ServerEvent

A fala do usuário começou ou parou.

responseCreated / responseDone

ServerEvent

Resposta iniciada ou encerrada. Verifique se responseDone.response.status é completed, cancelado ou falhou.

functionCall

{ callId: string; name: string; arguments: string }

Argumentos completos da chamada. A aplicação analisa e valida a string JSON arguments.

ambientTranscript / ambientTranscriptCompleted

{ text: string; stash: string } / { transcript: string }

Transcrição atual ou final do áudio ambiente, excluída do contexto da conversa.

event

ServerEvent

Mensagem JSON original do serviço.

error

DashScopeError

Erro de conexão ou serviço.

close

{ code: number; reason: string }

Notificação de fechamento da conexão subjacente.