リアルタイム動画理解

接続と認証

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

フィールド型必須説明

model: string必須

モデルID。安定版IDまたはスナップショットIDをWebSocket接続先のmodelクエリパラメータに指定します

Authorization: HTTP header必須

Bearer <API Key>。クエリパラメータやWebSocketサブプロトコルによる指定には対応していません

セッションの流れ

段階	クライアント	サーバー側の応答と判定
接続の確立	WebSocketハンドシェイクを完了します	session.createdを受信します。接続時にセッションが自動作成されます
設定	session.configureを1回だけ送信します	session.configuredを受信し、session.readyを待ちます
画像の送信	まずinput.frame JSONを送信し、次に画像バイナリを送信します	input.frame.readyを待ってからバイナリを送信し、input.frame.acceptedを受信してから次の入力を送信します。画像だけでは回答は自動生成されません
質問	input.promptを単独で送信します	質問に画像を再度添付する必要はありません。accepted / processedを受信し、テキスト、沈黙、割り込みのイベントを受信する場合があります
継続または終了	フレームの送信を続けるか、final=trueを設定する / session.abortを送信します	response.doneは1つの回答セグメントを終了するだけで、セッションを終了するのはsession.doneです

クライアントイベント

フィールド型説明

session.configure: event

接続の確立後に必ず1回送信し、session.created.configure_timeout_sの期限内に完了する必要があります。

input.frame: event

画像フレームのメタデータを送信します。input.frame.readyを受信したら、続けて完全な画像バイナリを送信します。

input.prompt: event

質問テキストを単独で送信します。フィールド名はtextではなくpromptです。質問には直近に受信した画像が使われます。

session.abort: event

セッション全体を能動的に終了します。seq_noを消費せず、その他のフィールドも受け付けません。

サーバーイベント

フィールド型説明

セッションイベント: server events

接続、設定、準備完了、セッションの終了状態の判定に使用します。

入力イベント: server events

画像フレームや質問の受信準備、送信、処理完了を確認するために使用します。

出力イベント: server events

増分テキストの読み取りと、1つの回答セグメントが沈黙、割り込み、正常終了のいずれであるかの判定に使用します。

使用量イベント: server events

処理中の使用量と、回答またはセッションの累計使用量の読み取りに使用します。

エラーイベント: server events

プロトコルやサービスの異常の処理に使用します。

プロトコルの制限

項目	現在のプロトコル値と説明
制御イベント	1件あたりデフォルトで256 KiB以下で、画像バイナリのサイズとは別に計算します
設定と送信	サーバーが定める設定期限内に設定を完了します。input.frame.readyの受信後10秒以内にバイナリを送信してください。タイムアウトするとcode=session_timeoutのerrorイベントが返され、セッションが終了します
入力キュー	デフォルトは4、設定可能な範囲は`[1, 256]`です。未処理入力の枠であり、セッションの同時実行数ではありません
コンテキストと時間	サーバーが返すcontext_limitとセッション時間の制限のうち、先に達した方が適用されます

エラーコード

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

エラーコード	発生条件	対処方法
invalid_request	クライアントのイベント/フィールド/順序が不正であるか、メッセージが大きすぎます	リクエストを修正して再送信してください。接続が切断された場合は再接続してください
context_exhausted	セッションがコンテキストの上限に達しました	現在のセッションを終了し、新しいセッションを確立してください
session_timeout	セッションが時間またはアイドルの制限に達したか、input.frame.readyの受信後10秒以内にバイナリが送信されませんでした	セッションのアクティビティとサーバーの制限を確認し、必要に応じて再接続してください
response_failed	モデルの生成または処理に失敗しました	エラー情報を記録し、業務に応じて再試行するかどうかを判断してください
session_capacity_exceeded	リアルタイムセッションの容量が上限に達しました	同時実行数を減らすか、しばらくしてから再試行してください

接続のクローズ

クローズコード	意味	クライアントの対応
1000	サーバーがsession.doneを送信した後にクローズします。errorイベントで終了したセッションもこのクローズコードを使用します	現在のセッションを終了し、再試行しないでください。成否はsession.done.reason（completed、aborted、errorなど）とそれ以前のerrorイベントで判断してください
1001	サービスの停止または接続の離脱	業務の必要に応じて再接続してください
1002	プロトコルエラー	イベントの形式と送信順序を確認してから再試行してください
1009	バイナリのサイズ超過、または制御イベントが大きすぎます。クローズ前にinvalid_requestのerrorイベントが返される場合があります。	メッセージを小さくしてから再接続してください
1011	サーバーの障害	しばらくしてから再試行し、エラーを記録してください
1013	サービスが一時的に処理できません	同時実行数を減らし、しばらくしてから再試行してください

次のステップ

シナリオガイド

接続ガイドを見る

接続の確立から、画像フレームの送信、質問、セッションの終了まで。

モデル

モデル概要を見る

モデルID、機能、適用シーンを確認します。

リクエスト例

import asyncio
import json
import os
from pathlib import Path

from websockets.asyncio.client import connect
from websockets.exceptions import ConnectionClosed

URL = "wss://api.mosi.cn/v1/realtime?model=moss-vl-realtime-1.0"


async def receive_event(ws):
    try:
        message = await asyncio.wait_for(ws.recv(), timeout=30)
    except (ConnectionClosed, asyncio.TimeoutError) as error:
        raise RuntimeError("Disconnected or timed out before session.done; final state and usage unknown") from error
    if isinstance(message, bytes):
        raise RuntimeError("Unexpected binary server message")
    event = json.loads(message)
    if event["type"] in ("error", "input.frame.rejected"):
        raise RuntimeError(f"{event.get('code', event['type'])}: {event.get('message') or event.get('reason', '')}")
    if event["type"] == "response.text.delta":
        print(event["delta"], end="", flush=True)
    return event


async def wait_for(ws, event_type, seq_no=None):
    while True:
        event = await receive_event(ws)
        if event["type"] == event_type and (seq_no is None or event.get("seq_no") == seq_no):
            return event
        if event["type"] == "session.done":
            raise RuntimeError(f"Session ended before {event_type}: {event.get('reason')}")


async def main():
    frame = Path(__file__).with_name("frame.jpg").read_bytes()
    headers = {"Authorization": f"Bearer {os.environ['MOSS_API_KEY']}"}
    async with connect(URL, additional_headers=headers) as ws:
        await wait_for(ws, "session.created")
        await ws.send(json.dumps({
            "type": "session.configure",
            "prompt": "画面を観察して、私の質問に答えてください。",
        }))
        configured = await wait_for(ws, "session.configured")
        if len(frame) > configured["max_frame_bytes"]:
            raise ValueError("frame.jpg exceeds max_frame_bytes")
        await wait_for(ws, "session.ready")
        await ws.send(json.dumps({
            "type": "input.frame", "seq_no": 0,
            "timestamp": 0.0, "mime_type": "image/jpeg",
        }))
        await wait_for(ws, "input.frame.ready", 0)
        await ws.send(frame)
        await wait_for(ws, "input.frame.accepted", 0)
        await ws.send(json.dumps({
            "type": "input.prompt", "seq_no": 1,
            "prompt": "画面には何がありますか？", "final": True,
        }))
        while True:
            event = await receive_event(ws)
            if event["type"] == "session.done":
                print("\nFinal usage:", event.get("usage"))
                break


if __name__ == "__main__":
    asyncio.run(main())

import { readFile } from "node:fs/promises";
import WebSocket from "ws";

interface RealtimeEvent {
  type: string;
  seq_no?: number | null;
  max_frame_bytes?: number;
  delta?: string;
  code?: string;
  message?: string;
  reason?: string;
  usage?: unknown;
}

function isEvent(value: unknown): value is RealtimeEvent {
  return typeof value === "object" && value !== null
    && "type" in value && typeof value.type === "string"
    && (!("seq_no" in value) || value.seq_no === null || typeof value.seq_no === "number")
    && (!("max_frame_bytes" in value) || typeof value.max_frame_bytes === "number")
    && (!("delta" in value) || typeof value.delta === "string")
    && (!("code" in value) || typeof value.code === "string")
    && (!("message" in value) || typeof value.message === "string")
    && (!("reason" in value) || typeof value.reason === "string");
}

const keyValue = process.env.MOSS_API_KEY;
if (!keyValue) throw new Error("Set MOSS_API_KEY in your server environment");
const frame = await readFile(new URL("./frame.jpg", import.meta.url));
const ws = new WebSocket(
  "wss://api.mosi.cn/v1/realtime?model=moss-vl-realtime-1.0",
  { headers: { Authorization: `Bearer ${keyValue}` } },
);
let completed = false;
// Client-side idle guard, not a server SLA.
let idleTimer: ReturnType<typeof setTimeout>;
function fail(error: unknown): void {
  console.error(error);
  process.exitCode = 1;
  clearTimeout(idleTimer);
  ws.terminate();
}
function resetIdleTimer(): void {
  clearTimeout(idleTimer);
  idleTimer = setTimeout(() => fail(new Error("No event for 30 seconds; final state and usage unknown")), 30_000);
}
resetIdleTimer();
ws.on("error", fail);
ws.on("close", () => {
  clearTimeout(idleTimer);
  if (!completed) {
    console.error("Closed before session.done; final state and usage unknown");
    process.exitCode = 1;
  }
});
ws.on("message", (data, isBinary) => {
  try {
    if (isBinary) throw new Error("Unexpected binary server message");
    const event: unknown = JSON.parse(data.toString());
    if (!isEvent(event)) throw new Error("Invalid server event");
    resetIdleTimer();
    switch (event.type) {
      case "session.created":
        ws.send(JSON.stringify({ type: "session.configure", prompt: "画面を観察して、私の質問に答えてください。" }));
        break;
      case "session.configured":
        if (event.max_frame_bytes === undefined || frame.length > event.max_frame_bytes) {
          throw new Error("frame.jpg exceeds max_frame_bytes or limit is missing");
        }
        break;
      case "session.ready":
        ws.send(JSON.stringify({ type: "input.frame", seq_no: 0, timestamp: 0, mime_type: "image/jpeg" }));
        break;
      case "input.frame.ready":
        if (event.seq_no === 0) ws.send(frame);
        break;
      case "input.frame.accepted":
        if (event.seq_no === 0) ws.send(JSON.stringify({ type: "input.prompt", seq_no: 1, prompt: "画面には何がありますか？", final: true }));
        break;
      case "response.text.delta":
        process.stdout.write(event.delta ?? "");
        break;
      case "session.done":
        completed = true;
        clearTimeout(idleTimer);
        console.log("\nFinal usage:", event.usage);
        ws.close();
        break;
      case "error":
      case "input.frame.rejected":
        throw new Error(`${event.code ?? event.type}: ${event.message ?? event.reason ?? ""}`);
    }
  } catch (error) {
    fail(error);
  }
});

レスポンス例

{"type":"session.created","session_id":"session_xxx","task_id":"task_xxx","model":"moss-vl-realtime-1.0-2026-09-09","turn_id":0,"configure_timeout_s":180,"protocol_version":"vl-api-v2","capabilities":["session.usage","response.done.usage","session.done.usage","error.seq_no","input.frame.rejected","response.done.per_response","response.id","usage.text_input_output"]}
{"type":"session.configured","session_id":"video_sess_xxx","request_id":"video_req_xxx","max_frame_bytes":8388608,"input_queue_capacity":4,"max_tokens_per_turn":86400,"parked_request_timeout_s":3600,"context_limit":131072}
{"type":"session.ready","session_id":"video_sess_xxx","request_id":"video_req_xxx","turn_id":0}
{"type":"response.turn.silence","turn_id":0,"seq_no":null,"timestamp":null,"silence_seq":0}
{"type":"input.frame.ready","seq_no":0}
{"type":"input.frame.accepted","seq_no":0,"timestamp":0.0,"final":false,"pending_events":1,"interrupts_current_turn":false}
{"type":"input.frame.processed","seq_no":0,"timestamp":0.0,"final":false,"pending_events":0}
{"type":"input.prompt.accepted","seq_no":1,"final":true,"pending_events":1,"interrupts_current_turn":true}
{"type":"response.turn.interrupted","turn_id":0,"next_turn_id":1,"seq_no":1}
{"type":"input.prompt.processed","seq_no":1,"timestamp":0.0,"final":true,"pending_events":0,"interrupted_turn_id":0,"turn_id":1}
{"type":"response.text.delta","delta":"画面に車が1台あります。","turn_id":1,"response_id":"resp_xxx","response_seq":1}
{"type":"response.done","response_id":"resp_xxx","response_seq":1,"turn_id":1,"finish_reason":"stop","boundary":"silence","usage":{"vision_tokens":120,"text_input_tokens":9,"text_output_tokens":8,"text_tokens":17,"total_tokens":137}}
{"type":"session.done","reason":"completed","usage":{"vision_tokens":120,"text_input_tokens":9,"text_output_tokens":8,"text_tokens":17,"total_tokens":137}}

// その他のイベントはデフォルトのレスポンスと同じです。追加された使用量イベントのみを示します。
{
  "type": "session.usage",
  "decoder_tokens": 77,
  "encoder_tokens": 0,
  "encoder_kv_tokens": 0,
  "token_space_used": 77,
  "context_limit": 131072,
  "context_remaining": 130995
}