リアルタイム音声・映像対話

MOSS-Live 1.0は、自然で表現力豊かなリアルタイム対話のための全二重音声モデルです。聞きながら話すことができ、自然な割り込みに対応し、複雑な推論や長時間のタスクをお客様自身のバックエンドに委任して実行し、実行中もユーザーとの会話を続けます。リアルタイム動画ストリームの入力にも対応し、音声と映像から対話の状況を理解して、音声とテキストをストリーミングで出力します。

1. APIキーを作成

   APIキー管理プラットフォームでキーを作成し、サーバー側の環境変数に設定します。

   MOSS_API_KEY=<your_api_key_here>

2. 接続と認証

   サーバー側のWebSocketクライアントでAPIに接続します。クエリパラメータでモデルを指定し、ハンドシェイクのリクエストヘッダーでAPIキーを渡します。

   フィールド型必須説明

   model: query string必須

   モデルIDです。安定版IDを推奨し、スナップショットIDにも対応しています。WebSocket接続URLのmodelクエリパラメータで指定します。

   Authorization: HTTP header必須

   Bearer <API Key>。WebSocketハンドシェイクのリクエストヘッダーにのみ指定できます。

   wss://api.mosi.cn/v1/realtime?model=moss-live-1.0
   Authorization: Bearer $MOSS_API_KEY

3. セッションを作成

   接続に成功したら、まず次のJSONテキストフレームを送信します。

   {
     "action": "attach_session",
     "session_id": null
   }

   session_attachedを受信したらdata.session_idを保存し、音声の送信を開始します。基本的な対話はデフォルト設定で行えます。ペルソナ、ボイスの変更、ツール、クライアント委任が必要な場合は、APIリファレンスに従って設定してください。

   session.updateを送信した場合は、session.updatedを待ち、data.errorが空であることを確認してから入力を有効にします。接続または設定に失敗した場合は、先にエラーを処理し、メディアの送信を続けないでください。

4. リアルタイム音声を送信

   まずマイクを有効にします。

   {"action":"mic_state","enabled":true}

   音声をキャプチャして16 kHz、モノラル、ファイルヘッダーなしのPCM S16LEに変換し、WebSocketのバイナリフレームとしてリアルタイムの速度で送信し続けます。話し終えた後も無音フレームを送信し続け、モデルが間を判断できるようにします。

   音声のみの接続では、バイナリフレームでPCMをそのまま送信します。ブラウザアプリでは、音声とイベントをサーバー経由で中継し、APIキーはサーバー側に保存します。再生中もマイク音声のキャプチャと送信を続けます。

5. 回答の受信と表示

   セッションはモデルの音声を返し続け、ユーザーの音声テキストとモデルの音声テキスト（transcript）も提供します。字幕や対話履歴の表示に使えます。返された音声を順番に再生し、必要に応じて双方の音声テキストを表示してください。テキストイベントは{"action":"イベント名","data":{…}}の形式で、音声は別のWebSocketバイナリフレームで届きます。

   字幕と対話履歴を表示

   受信するイベント	アプリでの処理
   input.transcript.updated / input.transcript.done	data.textでユーザーの音声テキストを更新または確定します。
   output.transcript.updated / output.transcript.done	data.textでモデルの音声テキストを更新または確定します。

   data.textは現時点の全文です。更新のたびに該当するテキストを置き換え、追記しないでください。確定済みのユーザー音声テキストの修正と、返答との関連付けに使うフィールドはAPIリファレンスを参照してください。

   モデルの音声を再生

   1. response.audio.startedを受信したら、その返答の音声を受け取る準備をします。
   2. 各response.audio.contextには、次のバイナリ音声のrun_id、turn_id、chunk_idが含まれます。これらを保存し、受信した順に48 kHz、モノラル、PCM S16LEの音声を再生します。
   3. チャンクの再生が実際に終わったら、run_id、turn_id、chunk_idをそのまま付けてplayback.chunk.completedを送信します。
   4. response.audio.doneを受信し、その返答の音声がすべて実際に再生し終わったら、playback.completedを送信します。

   たとえば、音声チャンクを1つ再生し終えたら次を送信します。

   {
     "action": "playback.chunk.completed",
     "run_id": "<受信したrun_id>",
     "turn_id": "<受信したturn_id>",
     "chunk_id": "<受信したchunk_id>"
   }

   返答全体を再生し終えたら次を送信します。

   {
     "action": "playback.completed",
     "run_id": "<受信したrun_id>",
     "turn_id": "<受信したturn_id>"
   }

   再生確認はプレーヤーの実際の再生進捗に基づいて送信し、字幕はテキストイベントに従って個別に更新します。

6. 割り込みに対応して対話を続ける

   モデルが話している間にユーザーが話し始めても、アプリは音声の送信を続けます。response.audio.stopを受信したら、該当するrun_id、turn_idの再生を直ちに停止して再生待ちの音声をクリアし、続けてplayback.stoppedを送信します。接続は維持し、次の返答を受け取ります。

   まず再生し終えたチャンクを確認したうえで、再生途中のチャンクの再生済み時間played_audio_msを返します。まだ再生を始めていない場合は0です。フィールドと計算方法はAPIリファレンスを参照してください。

   response.interruptedを受信したら、run_id、turn_idに基づいてその返答を割り込み済み・終了としてマークし、「進行中」の状態を解除します。このイベントは今回の返答の最終状態です。接続を維持し、マイク音声の送信を続けて次の返答を受け取ります。上記の流れのとおりに再生を停止し、playback.stoppedを送信します。

7. 対話を終了

   WebSocketを閉じ、マイクのキャプチャを停止して、再生待ちの音声をクリアし、プレーヤーのリソースを解放します。動画を有効にしている場合は、カメラや画面のキャプチャも停止します。

   ws.close();
   stream?.getTracks().forEach(track => track.stop());
   // プレーヤーも停止し、再生待ちの音声をクリアします。

   接続を閉じると今回のセッションが終了します。課金情報については課金の説明を参照してください。

8. 接続を確認

   • 一言話すと、ユーザーの音声テキストが表示され、モデルの回答が聞こえる。
   • モデルの回答中に割り込むと、前の返答の再生が止まり、モデルが新しい入力に応答する。
   • 1ターンを最後まで再生すると、再生確認が送信済みで、output.transcript.doneとresponse.ended（data.status=completed）を受信している。
   • 対話を閉じると、マイク、動画のキャプチャ、プレーヤーがすべて停止している。

バックエンドサービスの設定

バックエンドサービスは、MOSS-Liveから委任された複雑な推論や長時間のタスクを受け取り、進捗と結果を非同期で返送します。対応済みのPiを使うことも、独自のHarnessを接続することもできます。

方法1：Piを使う

Piは対応済みです。バックエンドモデルのプロバイダー、Base URL、モデルID、APIキーを設定すれば使用できます。Node.js 22.19.0以上が必要で、macOSとLinuxに対応しています。Piは依存関係と一緒にインストールされます。

付属のサンプルでPiを起動し、対話を確認します。

npx @mossai/mosslive@0.1.0 demo

ターミナルの案内に従って設定を完了し、MOSS APIキーとバックエンドモデルのキーを入力したら、ターミナルに表示されたローカルのアドレスを開いて対話を開始します。設定はmoss-live.config.jsonに保存されます。キーは起動時に入力するほか、環境変数MOSS_API_KEYとCUSTOMER_BACKEND_KEYで指定することもできます。

サンプルでデフォルトで有効なのは読み取り専用ツールread / grep / find / lsのみで、pi.toolsで権限を調整できます。既存のアプリでPiを使う場合は、APIリファレンスのPi接続例を参照してください。

方法2：独自のHarnessを接続する

同じJavaScript SDKで独自のHarnessを接続し、タスクの実行、進捗の返送、結果の返却、キャンセル処理を実装します。まずアダプタープロジェクトを生成できます。

npx @mossai/mosslive@0.1.0 init-adapter --directory my-adapter

プロジェクトには実行器のテンプレート、AGENTS.md、契約テストが含まれます。ガイドに従ってアダプターを完成させたら、実行器をリアルタイム接続に接続します。インターフェースの詳細はAPIリファレンス：JavaScript SDKと実行器を参照してください。

バックエンドサービスの設定は任意です。リアルタイム対話とカスタムツールは単独で使用できます。

次のステップ