リアルタイム対話の作成

接続と認証

HTTP GETでWebSocketにアップグレードします。接続先はwss://api.mosi.cn/v1/realtimeで、modelクエリパラメータでモデルを指定する必要があります。APIキーはAuthorizationリクエストヘッダーにのみ指定できます。

フィールド型必須説明

model: query string必須

モデルIDです。moss-live-1.0で固定され、WebSocket URLのmodelクエリパラメータで渡します。

user: query string任意

呼び出し側が管理する安定したエンドユーザーIDで、URLエンコードが必要です。memory_scope=userを使用する場合は必須で、再接続時は同じuserを使用します。例：wss://api.mosi.cn/v1/realtime?model=moss-live-1.0&user=customer_001。

Authorization: HTTP header必須

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

セッションの流れ

段階	クライアント	サーバー側の応答と判定
接続の確立	WebSocketハンドシェイクを完了します	接続が開いた後にセッションに参加します
設定	attach_sessionを送信し、次にsession.updateを送信します	session_attached、session.updatedを順に待ち、data.errorが空文字列であることを確認します
音声と動画の送信	マイクを有効にします。映像を送る場合はmedia.modeとvideo.stateを有効にします	同じ接続で音声とJPEG映像を受信します
回答	テキストを表示し、音声を再生して、再生確認を送信します	input.transcript.done、output.transcript.done、response.endedを受信します
継続または終了	入力を続けるか、WebSocketを閉じます	このターンが完了すれば継続できます。接続を閉じるとセッションが終了します

クライアントイベント

フィールド型説明

attach_session: event

セッションに参加します。session_attachedを受信した時点から、オンライン時間に応じた課金が始まります。

session.update: event

ペルソナと業務ルールを設定します。session.updatedを受信したらdata.errorを確認してください。空でない場合、設定は反映されません。

mic_state: event

マイク入力をオンまたはオフにします。

media.mode: event

動画または画面共有の前にtagged-v1を有効にします。

メディア	上りのバイナリ形式
tagged-v1を有効にしていない音声	生のPCM S16LE。20 msで640バイト、WAVヘッダーなし。
tagged-v1を有効にした音声	0x00 + PCMの生バイト。20 msで641バイト。映像をオフにした後もプレフィックスは残ります。
カメラ	0x01 + JPEGの生バイト。画像1枚につき1メッセージ。
画面共有	0x02 + JPEGの生バイト。画像1枚につき1メッセージ。

video.state: event

カメラまたは画面の映像を制御します。映像をオフにしてもセッションは終了しません。

playback.chunk.completed: event

各音声チャンクの再生が実際に完了した後に送信します。フィールドはメッセージのトップレベルに置き、dataで囲みません。実際に再生が完了した音声のみを確認し、回答テキストの終了を待ってから確認しないでください。

playback.completed: event

response.audio.doneを受信し、このターンの音声がすべて再生し終わった後に送信します。

video.stream_focus: event

主に注目する映像ソースを設定します。

playback.stopped: event

response.audio.stopを受信した後、対応する再生を停止して返送します。

サーバーイベント

フィールド型説明

session_attached: event

セッションに参加しました。受信してからペルソナと業務ルールを設定します。

session.updated: event

設定の結果。data.errorが空文字列の場合に、メディアとマイクを有効にします。

input.transcript.updated: event

ユーザーの認識テキストの更新。data.textは現時点の全文のため、表示を置き換えてください。1件ずつ追記しないでください。

input.transcript.done: event

ユーザーの認識テキストの完了。

output.transcript.updated: event

モデルの回答テキストの更新。data.textは現時点の全文のため、表示を置き換えてください。1件ずつ追記しないでください。

output.transcript.done: event

モデルの回答テキストの完了。

response.interrupted: event

回答が割り込まれました。run_id、turn_idに基づいて、対応する回答を割り込み済みとしてマークします。

response.audio.context: event

音声コンテキストを保存し、後続のバイナリ音声と順番に対応付けます。

response.audio.done: event

このターンの音声の送信が完了しました。実際の再生がすべて完了した後にplayback.completedを送信します。

response.ended: event

このターンの状態通知。セッションの終了を意味するものではありません。

error: event

エラーイベント。原因を記録し、接続とメディアのリソースを解放します。

response.audio.stop: event

対応する音声の再生を停止し、playback.stoppedを送信します。

プロトコルの制限

項目	現在のプロトコル値と説明
音声	上り16 kHz、下り48 kHz、モノラルのPCM S16LE。WAVヘッダーは付けません。発話の終了後も無音を送信し続けます。
メディアのカプセル化	tagged-v1：音声は0x00、カメラのJPEGは0x01、画面のJPEGは0x02。映像をオフにした後も音声のプレフィックスは残ります。
映像	JPEGは1枚につき1件のバイナリメッセージで送信します。Base64は使用せず、MP4ファイル全体やH.264ストリームは受け付けません。
転送	音声と映像は同じWebSocketを共用します。
映像の処理	過負荷時は最新の映像を保持し、処理待ちの古いフレームを破棄することがあるため、フレーム単位の解析は保証されません。1 FPS、JPEG quality 0.8、カメラの長辺640 px、画面の長辺1024 pxはクライアントのデフォルト値であり、ハードリミットではありません。

エラーコード

接続確立時の認証、権限、レート制限、一般的なHTTPエラーについては、エラーコードを参照してください。以下では、MOSS-LIVE API固有のプロトコルエラーのみを示します。

エラーコード	発生条件	対処方法
memory_scope_requires_user	user記憶範囲でエンドユーザーの識別情報がありません	安定したuserを渡すか、session範囲を使用してください。
memory_scope_immutable	再接続時に作成時のオプションを変更しました	作成時のオプションで再接続してください。オプションを変更するには新しいセッションを作成してください。
invalid_memory_scope	パラメータの値が不正です	列挙値を確認してください。

次のステップ

モデル

MOSS-LIVEのモデル詳細を見る

モデルID、対応モダリティ、リアルタイムインタラクション機能を確認します。

モデル概要

モデル一覧を見る

モデルの機能を比較し、現在のシナリオに適したモデルを選択します。

リクエスト例

import asyncio, json, os
import websockets

URL = "wss://api.mosi.cn/v1/realtime?model=moss-live-1.0"
HEADERS = {
    "Authorization": "Bearer " + os.environ["MOSS_API_KEY"],
}

async def main():
    async with websockets.connect(URL, additional_headers=HEADERS) as ws:
        await ws.send(json.dumps({"action": "attach_session"}))
        async for packet in ws:
            if isinstance(packet, bytes):
                # response.audio.contextと対応付け、48 kHz PCM S16LEとして再生して再生確認を送信します。
                continue
            msg = json.loads(packet)
            data = msg.get("data") or {}
            action = msg.get("action")
            if action == "session_attached":
                await ws.send(json.dumps({"action": "session.update", "session": {
                    "persona": {"name": "アン", "prompt": "あなたはフレンドリーなアシスタントのアンです。"},
                    "instructions": "中国語で短く1文で答えてください。"}}))
            elif action == "session.updated":
                if data.get("error"):
                    raise RuntimeError(str(msg))
                await ws.send(json.dumps({"action": "media.mode",
                    "binary_protocol": "tagged-v1"}))
                await ws.send(json.dumps({"action": "video.state",
                    "source": "camera", "enabled": True}))
                await ws.send(json.dumps({"action": "mic_state", "enabled": True}))
                # リアルタイムのキャプチャタスクからアップロードします：
                # await ws.send(b"\x00" + pcm_bytes)   # 16 kHz PCM
                # await ws.send(b"\x01" + jpeg_bytes)  # カメラ
                # await ws.send(b"\x02" + jpeg_bytes)  # 画面
            elif action == "error":
                raise RuntimeError(str(msg))
            else:
                print(action, data)
# 接続と制御の例です。リアルタイムキャプチャ、再生キュー、再生確認のロジックは別途実装してください。
asyncio.run(main())

import WebSocket from 'ws';
const ws = new WebSocket('wss://api.mosi.cn/v1/realtime?model=moss-live-1.0', {
  headers: { Authorization: `Bearer ${process.env.MOSS_API_KEY}` }
});
const send = (value: object) => ws.send(JSON.stringify(value));
ws.on('open', () => send({ action: 'attach_session' }));
ws.on('message', (packet, isBinary) => {
  if (isBinary) {
    // response.audio.contextで対応付け、48 kHz PCMを再生して再生確認を送信します。
    return;
  }
  const msg = JSON.parse(packet.toString());
  const data = msg.data || {};
  if (msg.action === 'session_attached') {
    send({ action: 'session.update', session: {
      persona: { name: 'アン', prompt: 'あなたはフレンドリーなアシスタントのアンです。' },
      instructions: '中国語で短く1文で答えてください。' } });
  } else if (msg.action === 'session.updated') {
    if (data.error) { console.error(msg); ws.close(); return; }
    send({ action: 'media.mode', binary_protocol: 'tagged-v1' });
    send({ action: 'video.state', source: 'camera', enabled: true });
    send({ action: 'mic_state', enabled: true });
  } else if (msg.action === 'error') { console.error(msg); ws.close(); }
});
// セッションの準備ができたら、リアルタイムのキャプチャタスクから送信します。pcmBytes / jpegBytesはキャプチャしたデータです：
function sendAudio(pcmBytes: Buffer) {
  ws.send(Buffer.concat([Buffer.from([0x00]), pcmBytes]));
}
function sendCamera(jpegBytes: Buffer) {
  ws.send(Buffer.concat([Buffer.from([0x01]), jpegBytes]));
}
function sendScreen(jpegBytes: Buffer) {
  ws.send(Buffer.concat([Buffer.from([0x02]), jpegBytes]));
}
// 発話の終了後も全ゼロのPCMを送信し続けます。映像はまず1 FPSで結合テストできます。
// キャプチャ、再生、再生確認は別途実装してください。テスト終了時にws.close()を呼び出します。

レスポンス例

// 以下は個別に受信するWebSocketイベントの例です。
{"action":"session_attached","data":{"session_id":"<session_id>","memory_scope":"session","delegation":"none"}}
{"action":"session.updated","data":{"error":""}}
{"action":"input.transcript.done","data":{"text":"画面には何がありますか？"}}
{"action":"output.transcript.done","data":{"text":"画面に机が1つあります。","run_id":"<run_id>","turn_id":"<turn_id>"}}
{"action":"response.audio.context","data":{"chunk_id":"<chunk_id>","run_id":"<run_id>","turn_id":"<turn_id>"}}
// <48 kHzモノラルPCM S16LEのバイナリ。コンテキストと対応付けて再生し、再生確認を送信>
{"action":"response.audio.done","data":{"run_id":"<run_id>","turn_id":"<turn_id>"}}
{"action":"response.ended","data":{"status":"completed","run_id":"<run_id>","turn_id":"<turn_id>"}}