リアルタイム動画理解

MOSS-VL-Realtimeを使用して、1本のWebSocket接続でJPEG、PNG、またはWebPの画像フレームを継続的に送信し、同じセッション内で質問して増分テキストの回答を受け取ります。カメラや画面などのリアルタイム映像を理解するシナリオに適しています。

1. APIキーを作成

   APIキー管理プラットフォームでキーを作成し、サーバー側の環境変数でのみ使用してください。

   MOSS_API_KEY=<your_api_key_here>

2. 接続と認証

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

   フィールド型必須説明

   model: query string必須

   モデルIDです。moss-vl-realtime-1.0を使用します。スナップショットを固定する場合は、moss-vl-realtime-1.0-2026-09-09を使用できます。WebSocket接続URLのクエリパラメータに指定します。

   Authorization: HTTP header必須

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

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

3. セッションを設定

   接続に成功したら、まずsession.createdを受信し、次にsession.configureを1回送信します。サーバーからsession.configuredとsession.readyが返されるのを待ってから、映像や質問を送信できます。

   フィールド型必須説明

   type: string必須

   session.configureで固定です。

   prompt: string任意

   初期のユーザープロンプトです。デフォルトは空文字列です。

   max_new_tokens: integer任意

   新しい入力のたびにリセットされる生成枠です。デフォルトは4096で、セッション全体の出力上限ではありません。

   include_usage: boolean任意

   session.usage観測イベントを送信するかどうかです。デフォルトはfalseで、最終的な使用量の返却には影響しません。

   {
     "type": "session.configure",
     "prompt": "画面を観察し続けて、私の質問に答えてください。",
     "max_new_tokens": 128,
     "include_usage": false
   }

4. リアルタイム映像を送信

   カメラや画面の映像を画像フレームに変換します。まず1フレームを送信して素早く疎通を確認し、継続的な観察が必要な場合は、同じ手順で後続のフレームを送信し続けます。各フレームでは、まずinput.frameメタデータを送信し、input.frame.readyを受信したら画像のバイナリを送信し、input.frame.acceptedを受信してから次のフレームを送信します。映像を送信するだけでは回答は自動生成されません。質問は次のステップで別途送信します。

   フィールド型必須説明

   type: string必須

   input.frameで固定です。

   seq_no: integer必須

   画像フレームと質問で共有する、0から始まる連続したシーケンス番号です。

   timestamp: number必須

   映像のキャプチャ時刻で、単位は秒です。それまでに受け付けられたフレームのタイムスタンプより前の値にすることはできません。

   mime_type: string必須

   image/jpeg、image/png、またはimage/webpを指定し、実際のエンコードと一致させる必要があります。

   {
     "type": "input.frame",
     "seq_no": 0,
     "timestamp": 0.0,
     "mime_type": "image/jpeg"
   }

   そのフレームのinput.frame.readyを受信したら、JPEGファイルのバイナリ（バイト列）全体を送信します。画像をJSON、Base64、またはmultipartに入れることはできません。画像が受け付けられたら、次のフレームを送信することも、次のステップに進んで質問することもできます。

5. 質問を送信

   映像フレームの送信が完了したら、input.promptを別途送信して質問します。質問に画像を再度添付する必要はなく、サーバーは受信済みのリアルタイム映像に基づいて回答を生成します。final=falseの質問自体は回答をトリガーしません。質問後も前のステップの手順で映像フレームを送信し続ける必要があり、回答は後続のフレームが届いてから出力されます。

   フィールド型必須説明

   type: string必須

   input.promptで固定です。

   seq_no: integer必須

   映像フレームに続く、連続した次のシーケンス番号を使用します。

   prompt: string必須

   空でない質問テキストです。

   final: boolean任意

   デフォルトはfalseです。最後の質問ではtrueに設定してセッションを終了できます。

   {
     "type": "input.prompt",
     "seq_no": 1,
     "prompt": "画面の細部を説明してください。",
     "final": false
   }

   質問後も次のフレームを送信し続けます。番号は連続したseq_noを引き継ぎ、手順は前のステップと同じです。この例では質問後にもう1フレームを送信します。通常、モデルはこのフレームを処理した後に回答の出力を開始します。それでも出力がない場合は、フレームの送信を続けてください。

   {
     "type": "input.frame",
     "seq_no": 2,
     "timestamp": 1.0,
     "mime_type": "image/jpeg"
   }

6. 回答の受信と表示

   サーバーイベントを継続的に受信し、response.text.deltaのdeltaを順番に連結します。response_idで回答のセグメントを区別します。入力の確認を待っている間も、テキスト、エラー、クローズのイベントを処理する必要があります。

   {"type":"response.text.delta","delta":"画面に車が1台あります。","response_id":"resp_xxx","response_seq":0}
   {"type":"response.done","response_id":"resp_xxx","response_seq":0,"finish_reason":"stop"}

7. セッションを終了

   さらに質問を続ける場合は、次のシーケンス番号を引き続き使用できます。終了する準備ができたら、最後のinput.promptをfinal=trueに設定し、session.doneを受信するまでイベントの受信を続けます。途中で終了する場合は、session.abortを送信できます。これら2つの終了方法は、いずれか一方を使用してください。

   {
     "type": "input.prompt",
     "seq_no": 3,
     "prompt": "今見た内容を要約してください。",
     "final": true
   }

   {
     "type": "session.abort"
   }

8. 成功を確認

   この例の質問について、映像フレームを追加送信した後に空でないテキストを受信して連結し、最後にreason=completedのsession.doneを受信したことを確認します。モデルは一部の映像や質問に対して、正常な動作として何も出力しないことがあるため、テキストがないたびに呼び出しの失敗と判断しないでください。最初から最後までテキストがない場合は、まず質問後に映像フレームを送信し続けたかどうかを確認してください。

次のステップ