音声 Node.js SDK で Qwen-Audio-Realtime のセッション設定、音声の送受信、文字起こし、ツール呼び出しを行います。
SDK のインストール
Node.js 18 以降が必要です。SDK 0.1.0 パッケージをダウンロードし、プロジェクトで次を実行します。
クイックスタート
コンソールで API キーを取得し、環境変数 DASHSCOPE_API_KEY に設定します。
サンプル音声を input.mp3 として保存し、16 kHz、16-bit、モノラル PCM に変換します。
example.mjs として保存し、node example.mjs を実行します。
API リファレンス
コンストラクターのオプション
RealtimeClient のコンストラクターオプション:
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
apiKey | string | いいえ | API キー。デフォルトは DASHSCOPE_API_KEY。 |
workspaceId | string | いいえ | ワークスペース ID。デフォルトは DASHSCOPE_WORKSPACE_ID。 |
baseUrl | string | いいえ | サービスホスト名を dashscope-intl.aliyuncs.com(シンガポール)に設定します。 |
model | string | はい | モデル ID。 |
voice | string | いいえ | 音色 ID。省略時はサービスのデフォルト音色を使用します。 |
instructions | string | いいえ | 役割やスタイルなどを指定するシステム指示。 |
turnDetection | TurnDetection | null | いいえ | デフォルトは { type: "server_vad" }。null は手動送信です。smart_turn と smart_turn_v2 にも対応します。 |
modalities | Array<'text' | 'audio'> | いいえ | 出力モダリティ。デフォルト:["text", "audio"]。 |
maxHistoryTurns | number | いいえ | 履歴ターン数:[1,50]。サービスのデフォルト:20。 |
tools | ToolDefinition[] | いいえ | ツール定義。アプリがツールを実行し、引数を検証します。 |
inputTranscription | { model?: string; language?: string } | null | いいえ | 入力文字起こし設定。例:{ model: "fun-asr", language: "zh" }。null で無効化します。 |
sessionExtras | SessionConfig | いいえ | 追加セッション設定(speech_rate、enable_search など)。対応するトップレベル設定を上書きします。フィールドはクライアントイベントを参照してください。 |
connectTimeoutMs | number | いいえ | 接続タイムアウト(ms)。デフォルト:10000。 |
主なメソッド
| メソッド | 戻り値 | 説明 |
|---|---|---|
connect() | Promise<void> | 接続して設定を送信し、sessionUpdated で反映を確認します。 |
updateSession(session: SessionConfig) | void | セッションを更新し、sessionUpdated で確認します。 |
appendAudio(pcm: Buffer | Uint8Array) | void | 16 kHz、16-bit、モノラル PCM を送信します。 |
commit() | void | 手動モードで音声バッファーを確定します。 |
clearAudioBuffer() | void | 未確定の音声バッファーを消去します。 |
createResponse(response?: Record<string, unknown>) | void | モデルの応答生成を要求します。 |
cancelResponse() | void | 現在の応答をキャンセルし、セッションは維持します。 |
createConversationItem(item: ConversationItem, previousItemId?: string) | void | 履歴やツール結果を追加します。previousItemId で挿入位置を指定します。 |
submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean) | void | ツール結果文字列を送信します。autoCreateResponse はデフォルト true で、次の応答を要求します。 |
deleteConversationItem(itemId: string) | void | 指定した対話項目を削除します。 |
retrieveConversationItem(itemId: string) | void | 対話項目を照会し、event で受信します。 |
sendEvent(event: ClientEvent) | void | 元のクライアントイベントを送信します。 |
close(code?: number, reason?: string) | void | セッションと WebSocket 接続を閉じます。 |
コールバックイベント
on(event, listener) でコールバックを登録します。全フィールドはサーバーイベントを参照してください。
| イベント | ペイロード | 説明 |
|---|---|---|
open | void | 接続が確立し、初期設定が送信されました。 |
sessionCreated / sessionUpdated | ServerEvent | セッションの作成または設定の確認。 |
audio | Buffer | バイナリ音声チャンク。複数回発生する場合があります。 |
audioTranscriptDelta | { delta: string } | 出力音声の文字起こしの差分テキスト。 |
outputTranscript | { transcript: string } | 出力音声の完全な文字起こし。 |
textDelta / textDone | { delta: string } / { text: string } | テキストのみのモダリティにおける差分または完全なテキスト。 |
inputTranscriptDelta | { text: string; stash: string } | text は確定、stash は暫定テキストです。追記せず、両者を組み合わせて表示内容を置き換えます。 |
inputTranscript | { transcript: string } | 入力音声の最終的な文字起こし。 |
speechStarted / speechStopped | ServerEvent | ユーザー音声の開始または停止を検出しました。 |
responseCreated / responseDone | ServerEvent | 応答の開始または終了。responseDone.response.status が completed、キャンセル、失敗のいずれかを確認します。 |
functionCall | { callId: string; name: string; arguments: string } | 完全なツール呼び出し引数。アプリが arguments の JSON 文字列を解析・検証します。 |
ambientTranscript / ambientTranscriptCompleted | { text: string; stash: string } / { transcript: string } | 環境音の現在または最終的な文字起こし。会話コンテキストには追加されません。 |
event | ServerEvent | 元のサービス JSON メッセージ。 |
error | DashScopeError | 接続またはサービスのエラー。 |
close | { code: number; reason: string } | 基になる接続の切断通知。 |