この Topic では、Qwen-Omni-Realtime API のクライアントイベントについて説明します。
このページは Qwen-Omni-Realtime のイベントリファレンスです。イベント定義は WebSocket アクセスを基準としています。AOQ と WebRTC は、それぞれのデータチャネルでモデルイベントを送受信し、メディアトラックでメディアを転送します。最初に WebSocket アクセス、WebRTC アクセス、または AOQ アクセスをお読みください。
session.update
WebSocket 接続後、session.update を送信してセッションを設定できます。後で設定を変更する場合は、変更する設定だけを送信してください。それ以外の設定は維持されます。
サーバーは受信したパラメーターを検証します。検証に成功すると、更新後の構成全体を session.updated で返します。検証に失敗した場合は error イベントを返します。
typestring(必須)イベントタイプ。常に session.update です。 | |
sessionobject（任意）セッション構成。Qwen3.8-Omni-Flash-Realtime では、セッションの更新時に session が必須です。入力トークンの合計上限は 196608 で、Qwen3.5-Omni-Realtime と同じ規則で計算します。
プロパティ modalities array（任意）モデルの出力モダリティ。有効値：
string（任意）生成される音声のボイス。サポートされているボイスのリストについては、「ボイスリスト」をご参照ください。デフォルト音声：
object （任意）入力音声と出力音声の設定。省略したフィールドは、既存のデフォルト値を維持します。
プロパティ input object （任意）ユーザーの入力音声の設定。
プロパティ format object （任意）入力形式とサンプリングレート。最初の音声を送信する前に、セッションが IDLE の間に設定します。音声入力の開始後は変更できません。
プロパティ type string （任意）qwen3.5-omni-plus-realtime と qwen3.5-omni-flash-realtime：pcm（デフォルト、モノラル 16 ビットの raw PCM）または wav（WAV コンテナ内のモノラル 16 ビット PCM）。Qwen3.8-Omni-Flash-Realtime のマルチチャネル入力には、デフォルトの pcm が必要です。sample_rateinteger （任意）qwen3.5-omni-plus-realtime と qwen3.5-omni-flash-realtime：8000、16000（デフォルト）、24000、48000 Hz。Qwen3.8-Omni-Flash-Realtime のマルチチャネル入力には、デフォルトの 16000 Hz が必要です。次の 4 つのフィールドは、WebSocket 経由の Qwen3.8-Omni-Flash-Realtime のマルチチャネル入力に適用されます。sample_formatstring （任意）PCM サンプル形式。s16le のみをサポートし、デフォルトも s16le です。channelsinteger （任意）入力チャネル数：1（デフォルト）、2、4。2 チャネルと 4 チャネルの空間音声は、通常音声の 2 倍の入力トークンを使用します。トークンの計算をご覧ください。packingstring （任意）サンプルの格納形式。interleaved のみをサポートし、デフォルトも interleaved です。channel_layoutstring （任意）デフォルトは channels によって異なり、1 チャネルは mono、2 チャネルは raw_mic_array、4 チャネルは foa_ambix です。明示的な値は channels と一致する必要があります。マルチチャネル入力には PCM、16000 Hz、s16le、interleaved が必要です。省略したフィールドはデフォルト値を使用し、指定するフィールドは有効な型と値にする必要があります。フィールドを省略する代わりに null を送信しないでください。object （任意）モデルの出力音声の設定。
プロパティ format object （任意）出力形式とサンプリングレート。セッション開始時、音声対話の開始前に設定します。
プロパティ type string （任意）qwen3.5-omni-plus-realtime と qwen3.5-omni-flash-realtime：pcm（デフォルト、モノラル 16 ビットの raw PCM）または wav（WAV コンテナ内のモノラル 16 ビット PCM）。sample_rateinteger （任意）qwen3.5-omni-plus-realtime と qwen3.5-omni-flash-realtime：8000、16000、24000（デフォルト）、48000 Hz。string（任意）Qwen3.8-Omni-Flash-Realtime のデフォルトの出力音声は Tina です。利用可能な音声と voice の値は、音声一覧をご覧ください。既存の統合では session.voice を引き続き使用できます。新規の統合には session.audio.output.voice を使用してください。両方を指定した場合、音声出力は session.audio.output.voice の音声を使用します。object | null （任意）入力音声の文字起こし設定。無効にするには null を設定します。
プロパティ model string （必須）値は qwen3-asr-flash-realtime 固定です。文字起こしを有効にするには {"model":"qwen3-asr-flash-realtime"} を設定します。モデル値は変更できません。Python SDK の enable_input_audio_transcription は update_session メソッドの引数であり、session.update のトップレベルのフィールドではありません。string（任意）ユーザーの入力音声形式。現在は pcm のみをサポートします。入力音声はサンプリングレート 16 kHz の PCM 音声ストリームにする必要があります。output_audio_formatstring（任意）モデルの出力音声形式。現在は pcm のみをサポートします。出力音声はサンプリングレート 24 kHz の PCM 音声ストリームです。smooth_outputboolean | null（任意）このパラメーターは qwen3-omni-flash-realtime-2025-09-15 にのみ適用されます。口語的な応答スタイルを有効にするかどうかです。有効値：
string（任意）モデルのロールや目的を設定するシステムメッセージです。新しい instructions の値は、既存の instructions の値全体を置き換えます。内容は追記されません。ロールを維持するには、元のロール設定と新しい要件をまとめて送信してください。turn_detectionobject（任意）音声アクティビティ検出（VAD）の設定。セッションの初回設定時に省略すると、デフォルトパラメーターで VAD を有効にします。null に設定すると VAD を無効にし、クライアントが手動でモデル応答を開始します。
プロパティ type string（任意）VAD の種類。有効値：
float（任意）VAD の感度。値を小さくすると感度が高まり、背景ノイズなど小さな音も発話と判定しやすくなります。値を大きくすると、検出にはより明瞭で大きな発話が必要です。値の範囲は [-1.0, 1.0] です。デフォルト値は 0.5 です。silence_duration_msinteger（任意）発話終了後の最小無音時間（ミリ秒）。この時間を超えるとモデルが応答を生成します。値を小さくすると応答が速くなりますが、短い間で誤検出する場合があります。デフォルト値は 800 です。パラメーターの範囲は 200 から 6000 です。idle_timeout_msinteger（任意）qwen3.5-omni-plus-realtime と qwen3.5-omni-flash-realtime の server_vad モードにのみ適用されます。アイドルタイムアウト（ミリ秒）。サーバーの音声再生完了後、ユーザーがこの時間を超えて発話しない場合（speech.started が発生しない場合）、モデルは現在のコンテキストに基づいて応答を自発的に生成し、会話の継続を促します。タイムアウトは、最後のモデル応答の音声再生完了後から計測します。有効範囲：[5000, 30000]。boolean（任意）Qwen3.8-Omni-Flash-Realtime と Qwen3.5-Omni-Realtime に適用されます。Web 検索を有効にするかどうかです。デフォルトは false です。有効にすると、モデルは最新情報への質問に答えるため、検索するかどうかを自律的に判断します。tools と enable_search は互換性がありません。同時に有効にしないでください。search_options object（任意）Web 検索の設定。enable_search が有効な場合のみ適用されます。
プロパティ enable_source boolean（任意）検索結果の出典一覧を返すかどうかです。有効にするには true を設定します。object （任意）Qwen3.8-Omni-Flash-Realtime の動画入力設定。
プロパティ input object （任意）動画入力のパラメーター。
プロパティ representation_compact string （任意）動画表現の集約。セッションの初期デフォルトは none で、入力の細部をすべて保持します。細かな視覚情報が不要な場合、normal は集約して計算量を削減します。同じ動画入力で、トークン数は none の 4 分の 1 になります。トークンの計算をご覧ください。最初の音声を送信する前に設定します。音声入力開始後は変更できません。array（任意）ツール定義の一覧。モデルはユーザー入力に基づき、ツールを呼び出すかどうかを判断します。Qwen3.8-Omni-Flash-Realtime は、同じセッションに Function Calling と MCP ツールを設定できます。配列要素は type で区別します。tools と enable_search は同時に有効にできません。
Function Calling（type=function） type string （必須）function にする必要があります。functionobject （必須）カスタム関数の定義。
プロパティ name string （必須）関数名。get_current_weather、get_current_time など、実際の関数名と一致させます。descriptionstring （任意）関数の動作の説明。モデルはこれを使用して、ツールを呼び出すかどうかを判断します。parametersobject （任意）関数の入力パラメーター。モデルはこれを使用してパラメーター値を抽出します。入力のない関数では省略します。
プロパティ type string （必須）object にする必要があります。propertiesobject （任意）各入力パラメーターを名前で定義します。右の例の location はカスタムパラメーター名で、その type と description はデータ型と用途を説明します。requiredarray （任意）必須のパラメーターを列挙します。
MCP (type=mcp) Qwen3.8-Omni-Flash-Realtime の MCP 設定と呼び出しフローは、対話フローをご覧ください。この MCP 配列要素が存在する場合、必須フィールドを指定する必要があります。追加と更新のたびに server_label と server_url の両方が必要です。ラベルだけで既存設定を再利用することはできません。アクティブな Response がない場合のみ MCP 設定を更新してください。接続、検出、呼び出しにはクォータとタイムアウトが適用されます。MCP 呼び出し制限をご覧ください。typestring （必須）mcp にする必要があります。server_labelstring （必須）セッション内で一意の MCP サーバーラベル。1～64 文字で、英字、数字、アンダースコア、ハイフンのみ使用できます。server_urlstring （必須）MCP Streamable HTTP エンドポイント。ポート 443 の公開 HTTPS アドレスで、最大 4096 文字です。ユーザー名、パスワード、フラグメントを含めてはいけません。ドメインはパブリックアドレスに解決される必要があります。authorizationstring （任意）送信する Authorization の値。最大 8192 文字の表示可能な ASCII 文字。headersobject （任意）追加の送信 HTTP ヘッダー。文字列同士のペアを最大 16 個指定できます。名前は標準 HTTP ヘッダー名の文字で 1～128 文字、値は最大 8192 文字の表示可能な ASCII 文字です。名前は mcp-、proxy-、x-forwarded- で始めることや、host、authorization、connection、content-length、transfer-encoding、accept、content-type、forwarded、cookie、origin、upgrade、te、trailer と一致させることはできません。allowed_toolsarray of strings （任意）検出後に適用するフィルター。省略するとすべてのツールを許可し、空の配列では何も公開しません。各名前は 1～64 文字で、英字、数字、アンダースコア、ピリオド、ハイフンのみ使用できます。require_approvalstring （任意）承認ポリシー：always（デフォルト）または never。server_url、authorization、headers はサーバー側の接続にのみ使用し、session.updated には返されません。このイベントから機密設定を復元しないでください。 | |
temperaturefloat（任意）サンプリング温度。出力の多様性を制御します。値を大きくすると内容が多様になり、小さくすると出力がより確定的になります。有効範囲：[0, 2)。temperature と top_p はどちらも多様性を制御するため、片方だけを設定してください。デフォルト値：
| |
top_pfloat（任意）nucleus sampling の確率しきい値。出力の多様性を制御します。値を大きくすると内容が多様になり、小さくすると出力がより確定的になります。有効範囲：(0, 1.0]。temperature と top_p はどちらも多様性を制御するため、片方だけを設定してください。デフォルト値：
| |
top_kinteger（任意）サンプリングの候補集合サイズ。たとえば 50 は、各生成ステップをスコア上位 50 トークンに制限します。値を大きくするとランダム性が高まり、小さくすると確定性が高まります。null または 100 より大きい値を設定すると top_k を無効にし、top_p のみを適用します。最小値：0。デフォルト値：
| |
max_tokensinteger（任意）返すトークン数の上限。
qwen3.8-omni-flash-realtime の有効範囲は [1, 65536] です。その他のモデルでは、デフォルト値と最大値はモデルの最大出力長と同じです。モデル一覧をご覧ください。要約、キーワード抽出、コスト管理、レイテンシー削減などのタスクで、max_tokens を使用して出力長を制限します。 | |
repetition_penaltyfloat（任意）モデル出力の繰り返しを制御します。値を大きくすると繰り返しを減らし、1.0 はペナルティなしを意味します。qwen3.8-omni-flash-realtime は 0 も受け付けます。その他のモデルは 0 より大きい値が必要です。デフォルト値：
| |
presence_penalty float（任意）モデル出力の内容の繰り返しを制御します。有効範囲：[-2.0, 2.0]。正の値は繰り返しを減らし、負の値は繰り返しを増やします。デフォルト値：
| |
seedinteger（任意）生成の確定性を高めます。パラメーターを変えずに同じ seed を渡すと、実行間で一貫した結果を得られます。有効範囲：0～231−1。デフォルト：-1。 |
ツール設定の例
エンドポイント、認証情報、ツール名を実際の MCP サーバーの情報に置き換えます。
音声設定の例
2 チャネルの設定：
session.audio.output.voice の例（voice が longanlingxin の Long An Ling Xin 音声を使用）：
動画設定の例
動画集約の例：
response.create
response.create イベントは、モデル応答の生成をサーバーに指示します。VAD モードでは通常、発話の検出からサーバーが応答を開始します。ツール後の継続は、以下の明示的なフローに従います。Function Calling では、conversation.item.create でツール結果を返した後、このイベントを送信して生成を継続します。Qwen3.8-Omni-Flash-Realtime の MCP ツールはサーバーが実行します。モデルの継続応答が必要な場合は、この MCP 呼び出しを含む Response の response.done 後に、MCP 結果を添付せず response.create を 1 回送信します。
サーバーは response.created を返し、続いて conversation.item.created や response.content_part.added などの項目・コンテンツイベントを 1 つ以上返し、最後に response.done を返します。
typestring(必須)イベントタイプ。常に response.create です。 |
response.cancel
クライアントは進行中の応答をキャンセルするためにこのイベントを送信します。キャンセルする応答がない場合、サービスはエラーイベントで応答します。
typestring(必須)イベントタイプ。常に response.cancel です。 |
input_audio_buffer.append
WebSocket アクセス時に、入力音声バッファーへ音声バイトを追加します。
typestring(必須)イベントタイプ。常に input_audio_buffer.append です。 | |
audiostring(必須)Base64 エンコードされた音声データ。 |
input_audio_buffer.commit
ユーザー入力音声バッファーを送信して、会話に新しいユーザーメッセージアイテムを作成します。入力音声バッファーが空の場合、サービスはエラーイベントを返します。
- VAD モード: クライアントはこのイベントを送信する必要はありません。サービスは自動的に音声バッファーを送信します。
- 手動モード: クライアントはユーザーメッセージアイテムを作成するために音声バッファーを送信する必要があります。
input_audio_buffer.committed イベントで応答します。
クライアントが input_image_buffer.append イベントを送信した場合、input_audio_buffer.commit イベントは音声バッファーとともにイメージバッファーを送信します。
typestring(必須)イベントタイプ。常に input_audio_buffer.commit です。 |
input_audio_buffer.clear
バッファーから音声バイトをクリアします。サービスは input_audio_buffer.cleared イベントで応答します。
typestring(必須)イベントタイプ。常に input_audio_buffer.clear です。 |
input_image_buffer.append
WebSocket アクセス時に、画像バッファーへ画像データを追加します。画像はローカルファイルから取得するか、動画ストリームからリアルタイムでキャプチャできます。
画像入力には次の制限が適用されます。
- イメージフォーマットは JPG または JPEG である必要があります。推奨: 480p または 720p。最大: 1080p。
- Base64 エンコード後の 1 枚の画像は 256 KB 以下にする必要があります。エンコード前の元画像は 190 KB 未満を推奨します。
- 画像データは Base64 エンコードする必要があります。
- 推奨送信頻度：1 秒あたり 1 枚。
input_image_buffer.appendを送信する前に、少なくとも 1 回input_audio_buffer.appendイベントを送信します。
イメージバッファーは、input_audio_buffer.commit イベントを介して音声バッファーとともに送信されます。
typestring(必須)イベントタイプ。常に input_image_buffer.append です。 | |
imagestring（必須）Base64 エンコードされた画像データ。 |
conversation.item.create
Function Calling の結果、または Qwen3.8-Omni-Flash-Realtime の MCP 承認応答を対話項目として作成するには、このイベントを送信します。Function Calling では、ツールをローカルで実行し、結果を function_call_output として返してから response.create を送信します。MCP ツールはサーバーが実行します。承認には mcp_approval_response を使用し、承認応答の継続手順に従ってください。
event_idstring （任意）追跡用にクライアントが生成するイベント ID。typestring(必須)イベントタイプ。常に conversation.item.create です。 | |
itemobject（必須）作成する対話項目。空にできません。
プロパティ id string （任意）対話項目の ID。ローカル状態と対応させるには指定します。未指定の場合はサーバーが生成します。typestring （必須）Function Calling の結果には function_call_output、Qwen3.8-Omni-Flash-Realtime の MCP 承認応答には mcp_approval_response を使用します。call_idstring （条件付き必須）function_call_output の場合のみ必須です。response.function_call_arguments.done で返された call_id を使用します。outputstring （条件付き必須）function_call_output の場合のみ必須です。ツール関数の実行結果。approval_request_idstring （条件付き必須）mcp_approval_response の場合のみ必須です。未処理の mcp_approval_request の item.id と完全に一致する必要があります。approveboolean （条件付き必須）mcp_approval_response の場合のみ必須です。true は実行を許可し、false は呼び出しを拒否して failed にします。 |
MCP 承認応答（Qwen3.8-Omni-Flash-Realtime）
require_approval が always または未指定の場合、サーバーは mcp_approval_request を送信することがあります。上記の conversation.item.create フィールドを使用し、item.type="mcp_approval_response" で応答します。MCP ツールはサーバーが実行します。モデルの継続応答が必要な場合は、この MCP 呼び出しを含む Response の response.done を待ち、MCP 結果を添付せず response.create を 1 回送信します。
サーバーが返す承認リクエスト ID、項目 ID、イベント ID は不透明な文字列です。長さ、プレフィックス、生成規則に依存しないでください。
Qwen-Omni-Realtime をご覧ください。