Skip to main content

Qwen-Audio-Realtime Node.js SDK

Utilisez le SDK vocal Node.js pour configurer les sessions Qwen-Audio-Realtime, échanger de l’audio et gérer la transcription et les appels de fonctions.

Prérequis

Obtenez une clé API dans la console et définissez-la dans la variable d’environnement DASHSCOPE_API_KEY.

Installer le SDK

Nécessite Node.js 18 ou ultérieur. Téléchargez le SDK 0.1.0, puis exécutez dans votre projet :
npm install ./dashscope-sdk-nodejs-0.1.0.tgz

Démarrage rapide

Téléchargez l’audio d’exemple sous input.mp3 et convertissez-le en PCM mono 16 kHz, 16 bits :
ffmpeg -i input.mp3 -f s16le -ac 1 -ar 16000 input.pcm
Enregistrez l’exemple dans example.mjs, puis exécutez 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)
}

Paramètres de requête

Options du constructeur de RealtimeClient :
ParamètreTypeObligatoireDescription
apiKeystringNonClé API. Utilise DASHSCOPE_API_KEY par défaut.
workspaceIdstringNonID de l’espace de travail. Utilise DASHSCOPE_WORKSPACE_ID par défaut.
baseUrlstringNonDéfinissez l’hôte sur dashscope-intl.aliyuncs.com (Singapour).
modelstringOuiID du modèle.
voicestringNonID de voix. Utilise la voix par défaut du service si omis.
instructionsstringNonInstructions système pour le rôle, le style et le comportement.
turnDetectionTurnDetection | nullNonPar défaut : { type: "server_vad" }. null active l’envoi manuel. Accepte aussi smart_turn et smart_turn_v2.
modalitiesArray<'text' | 'audio'>NonModalités de sortie. Par défaut : ["text", "audio"].
maxHistoryTurnsnumberNonTours d’historique : [1,50]. Par défaut : 20.
toolsToolDefinition[]NonDéfinitions d’outils. L’application les exécute et valide les arguments.
inputTranscription{ model?: string; language?: string } | nullNonConfiguration de transcription d’entrée, par exemple { model: "fun-asr", language: "zh" } ; null la désactive.
sessionExtrasSessionConfigNonRéglages supplémentaires, tels que speech_rate et enable_search. Remplacent les réglages correspondants de niveau supérieur ; consultez les événements client.
connectTimeoutMsnumberNonDélai de connexion en ms. Par défaut : 10000.

Référence de l’API

Méthodes principales

MéthodeValeur de retourDescription
connect()Promise<void>Se connecte et envoie les réglages. sessionUpdated confirme leur application.
updateSession(session: SessionConfig)voidMet à jour la session ; confirmez avec sessionUpdated.
appendAudio(pcm: Buffer | Uint8Array)voidEnvoie du PCM mono 16 kHz, 16 bits.
commit()voidValide le tampon audio en mode manuel.
clearAudioBuffer()voidEfface le tampon audio non validé.
createResponse(response?: Record<string, unknown>)voidDemande une réponse au modèle.
cancelResponse()voidAnnule la réponse actuelle en conservant la session.
createConversationItem(item: ConversationItem, previousItemId?: string)voidAjoute l’historique ou un résultat d’outil. previousItemId définit la position.
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean)voidSoumet le résultat sous forme de chaîne. autoCreateResponse vaut true par défaut et demande la réponse suivante.
deleteConversationItem(itemId: string)voidSupprime un élément de conversation.
retrieveConversationItem(itemId: string)voidRécupère un élément via event.
sendEvent(event: ClientEvent)voidEnvoie un événement client brut.
close(code?: number, reason?: string)voidFerme la session et la connexion WebSocket.

Événements de callback

Enregistrez les callbacks avec on(event, listener). Consultez les champs complets dans les événements serveur.
ÉvénementCharge utileDescription
openvoidConnexion établie et configuration initiale envoyée.
sessionCreated / sessionUpdatedServerEventCréation de session ou confirmation de configuration.
audioBufferBloc audio binaire ; peut être émis plusieurs fois.
audioTranscriptDelta{ delta: string }Texte incrémental de transcription de l’audio de sortie.
outputTranscript{ transcript: string }Transcription complète de l’audio de sortie.
textDelta / textDone{ delta: string } / { text: string }Texte incrémental ou complet en modalité texte seul.
inputTranscriptDelta{ text: string; stash: string }text est confirmé et stash provisoire. Remplacez l’affichage courant par leur combinaison au lieu de l’ajouter.
inputTranscript{ transcript: string }Transcription finale de l’audio d’entrée.
speechStarted / speechStoppedServerEventDébut ou fin de parole utilisateur.
responseCreated / responseDoneServerEventRéponse commencée ou terminée. Vérifiez si responseDone.response.status est completed, annulé ou en échec.
functionCall{ callId: string; name: string; arguments: string }Arguments complets de l’appel. L’application analyse et valide la chaîne JSON arguments.
ambientTranscript / ambientTranscriptCompleted{ text: string; stash: string } / { transcript: string }Transcription courante ou finale de l’audio ambiant, exclue du contexte.
eventServerEventMessage JSON brut du service.
errorDashScopeErrorErreur de connexion ou de service.
close{ code: number; reason: string }Notification de fermeture de la connexion sous-jacente.