Skip to main content

Qwen-Audio-Realtime クライアントイベント

Qwen-Audio-Realtime API のクライアントイベントリファレンス。

ユーザーガイド：リアルタイム音声対話（Qwen-Audio-Realtime）。イベントのやり取りの順序は、WebSocket アクセスをご覧ください。
このページは Qwen-Audio-Realtime のイベントリファレンスです。イベント定義は WebSocket アクセスを基準としています。AOQ と WebRTC は、それぞれのデータチャネルでモデルイベントを送受信し、メディアトラックでメディアを転送します。最初に WebSocket アクセス、WebRTC アクセス、または AOQ アクセスをお読みください。
WebSocket SDK の使用方法は、Android SDK、iOS SDK、HarmonyOS SDKをご覧ください。モデルとプロトコルの選択は、概要をご覧ください。

session.update

説明：接続確立後、このイベントを送信してデフォルトのセッション設定を更新します。変更wantフィールドのみを含めてください。省略されたフィールドは現在の値を維持します。いずれかのパラメータが無効な場合、サーバーはエラーを返します。すべてのパラメータが有効な場合、サーバーは変更を適用し、完全な設定を返します。
turn_detection は、最初の音声が送信される前（IDLE 状態）にのみ変更できます。
typestring(必須)イベントタイプ。固定値：session.update。sessionobject (任意)セッション設定。

プロパティ

modalitiesarray (任意)モデルの出力モダリティ。有効な値は以下の通りです。
  • ["text"] テキストのみ。
  • ["audio", "text"]（デフォルト） テキストと音声の両方。
voicestring (任意)TTS音声名です。デフォルト値は、3.1 Plus の場合は longanqian_v3.1、3.0 Plus/Flash の場合は longanqian です。システム音声とクローン音声がサポートされています。最初の session.update でのみ設定可能で、後続の呼び出しでは無視されます。
  • 3.1 Plus 専用の追加システム音声：longanqian_v3.1、longanhuan_v3.1、longanlingxin_v3.1、longanfengyue_v3.1、xunanchuan_v3.1、beth_v3.1、betty_v3.1、cally_v3.1。
  • 3.1 Plus および 3.0 Plus/Flash で共有されるシステム音声：利用可能な値は longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng です。
  • クローン音声：音声クローニング APIで音声を作成し、このパラメーターを返された voice_id に設定します。詳しくは、音声の設定をご覧ください。
qwen-audio-3.1-realtime-plus に接続後、最初の session.update で音声を設定します。例：
{
    "type": "session.update",
    "session": {
        "voice": "longanqian_v3.1"
    }
}
enable_speech_emotionboolean (任意)音声感情強調を有効にするかどうかを指定します。有効にすると、応答音声の感情変化がより顕著になります。デフォルト値は true です。有効な値は true および false です。instructionsstring (任意)モデルの役割、応答スタイル、および動作の好みを定義するシステム指示です。セッション全体に適用されます。input_audio_formatstring (任意)入力音声フォーマットです。現在サポートされているのは pcm（16 kHz、16 ビット、モノラル）のみであり、これがデフォルト値です。最初の音声送信前（IDLE状態）にのみ変更できます。output_audio_formatstring (任意)出力音声フォーマットです。現在サポートされているのは pcm（24 kHz、16 ビット、モノラル）のみであり、これがデフォルト値です。input_audio_transcriptionobject (任意)入力音声の文字起こし設定です。qwen-audio-3.1-realtime-plus に適用されます。
languagestring (任意)入力音声のソース言語です。有効な値：
  • zh：中国語
  • en：英語
  • ja：日本語
  • ko：韓国語
  • vi：ベトナム語
  • th：タイ語
  • id：インドネシア語
  • ms：マレー語
  • tl：フィリピノ語
  • hi：ヒンディー語
  • ar：アラビア語
  • fr：フランス語
  • de：ドイツ語
  • es：スペイン語
  • pt：ポルトガル語
  • ru：ロシア語
  • it：イタリア語
  • nl：オランダ語
  • sv：スウェーデン語
  • da：デンマーク語
  • fi：フィンランド語
  • no：ノルウェー語
  • el：ギリシャ語
  • pl：ポーランド語
  • cs：チェコ語
  • hu：ハンガリー語
  • ro：ルーマニア語
  • bg：ブルガリア語
  • hr：クロアチア語
  • sk：スロバキア語
output_audioobject (任意)出力音声の設定です。qwen-audio-3.1-realtime-plus に適用されます。
languagestring (任意)出力音声のターゲット言語です。このパラメータは音声合成 (TTS) に作用します。可能な限りターゲット言語で音声が出力されますが、常に有効になるとは限らず、モデルが返すテキストの言語も変わりません。ターゲット言語のテキストを生成する必要がある場合は、プロンプトで明示的に指示してください（例：instructions で回答言語を指定する）。有効な値：
  • zh：中国語
  • en：英語
  • fr：フランス語
  • de：ドイツ語
  • ja：日本語
  • ko：韓国語
  • ru：ロシア語
  • pt：ポルトガル語
  • th：タイ語
  • id：インドネシア語
  • vi：ベトナム語
  • es：スペイン語
  • it：イタリア語
  • ms：マレー語
  • fil：フィリピノ語
  • ar：アラビア語
max_history_turnsinteger (任意)単一のリクエストに含まれる会話ターン数（質問と回答のペア）の最大値です。有効な値は 1 から 50 です。デフォルト値は 20 です。enable_searchboolean (任意)qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、および qwen-audio-3.0-realtime-flash モデルに適用されます。Web検索を有効にするかどうかを指定します。デフォルト値は false です。有効にすると、モデルはリアルタイムのクエリに基づいてWeb検索を行うかどうかを判断します。
tools と enable_search を同時に有効にすることはできません。
search_optionsobject (任意)Web検索の設定です。このパラメータは、enable_search が true に設定されている場合にのみ有効になります。
enable_sourceboolean (任意)検索結果の出典を返すかどうかを指定します。出典を返す場合は、このパラメータを true に設定します。
toolsarray (任意)Function Calling用のツール定義です。設定すると、モデルはユーザー入力に基づいてツールを呼び出すかどうかを判断します。
typestring(必須)固定値：function。function.namestring(必須)ツール関数の名前。function.descriptionstring (任意)ツール関数の説明です。モデルはこの情報を使用して、ツールを呼び出すかどうかを判断します。function.parametersobject (任意)ツール関数の入力パラメータの説明です。モデルはこの情報を使用して必要なパラメータを抽出します。関数がパラメータを取らない場合は、このフィールドを省略してください。
typestring(必須)固定値：object。propertiesobject (任意)各パラメータの名前、データ型、および説明を記述します。requiredarray (任意)必須となるパラメータを指定します。
turn_detectionobject|null (任意)ターン検出の設定です。プッシュトゥートークモードに切り替えるには、このフィールドを null に設定します。プッシュトゥートークモードでは、音声の手動コミットと推論の手動トリガーが必要です。このフィールドが指定されない場合、VADはデフォルトパラメータで有効になります。
typestring (任意)VAD タイプ。有効な値は以下の通りです。
  • server_vad（デフォルト）：音響特徴に基づいて発話の開始と終了を検出し、自動的に推論をトリガーします。
  • smart_turn：音響認識と意味理解を組み合わせてターンの境界を決定するインテリジェントなターン検出モードです。「えーと」や「あのー」といったフィラー音は、新しいターンをトリガーしたり、モデルの再生を中断したりしません。
thresholdfloat (任意)VAD感度です。server_vad モードでのみ有効です（smart_turn モードでは無視されます）。値を小さくするとVAD感度が上がり、かすかな音（背景雑音を含む）を発話として検出しやすくなります。値を大きくすると感度が下がり、検出をトリガーするためにより明瞭で大きな発話が必要になります。範囲：[-1.0, 1.0]。デフォルト：0.5。silence_duration_msinteger (任意)発話終了後、モデルの応答をトリガーするまでの最小無音時間（ミリ秒単位）です。server_vad モードでのみ有効です（smart_turn モードでは無視されます）。値を小さくすると応答が速くなりますが、短い一時停止中に false トリガーが発生する可能性があります。範囲：[200, 6000]。デフォルト：800。会話での推奨範囲：400-800。voiceprint_audio_urlsarray (任意)smart_turn モードでのみ有効です。 ターゲットユーザーの事前録音済み音声サンプルを指す公開アクセス可能なURLのリストで、話者強調に使用されます。登録されると、モデルはデュプレックス会話中にターゲット話者をロックオンし、他の音声や背景雑音を効果的に無視します。最大 5 URLまで指定可能です。音声フォーマットの要件：16kHz PCMまたはWAV。
このパラメータは、最初の session.update イベントでのみ設定できます。後続の session.update イベントでは無視されます。
{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}
言語設定（qwen-audio-3.1-realtime-plus）qwen-audio-3.1-realtime-plus に接続後、以下の session.update イベントを送信すると、入力音声のソース言語を中国語、出力音声のターゲット言語を英語に設定できます。
{
    "type": "session.update",
    "session": {
        "input_audio_transcription": {
            "language": "zh"
        },
        "output_audio": {
            "language": "en"
        }
    }
}
Function Calling:
{
    "type": "session.update",
    "session": {
        "modalities": [
            "text",
            "audio"
        ],
        "voice": "longanqian",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get weather for a specified city",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {
                                "type": "string",
                                "title": "City"
                            }
                        },
                        "required": ["city"]
                    }
                }
            }
        ],
        "turn_detection": {
            "type": "server_vad",
            "threshold": 0.5,
            "silence_duration_ms": 800
        }
    }
}
声紋登録 (voiceprint_audio_urls):
{
    "type": "session.update",
    "session": {
        "turn_detection": {
            "type": "smart_turn",
            "voiceprint_audio_urls": [
                "https://example.com/speaker1.pcm",
                "https://example.com/speaker2.wav"
            ]
        }
    }
}

input_audio_buffer.append

説明：WebSocket アクセス時に、入力バッファーへ音声データを追加します。20~40 ms ごとに 1 フレームなど、短い間隔で継続的に送信してください。サーバーはこのイベントに確認応答を返しません。
typestring(必須)イベントタイプ。固定値：input_audio_buffer.append。audiostring(必須)Base64 エンコードされた音声データ。
{
    "type": "input_audio_buffer.append",
    "audio": "<Base64-encoded audio data>"
}

input_audio_buffer.commit

説明：プッシュトゥートークモード専用。 バッファリングされた音声をユーザーメッセージとしてコミットします。これだけでは推論は自動的にトリガーされません。推論を手動でトリガーするには response.create を送信してください。 このイベントは server_vad および smart_turn モードでは無視されます。
typestring(必須)イベントタイプ。固定値：input_audio_buffer.commit。
{
    "type": "input_audio_buffer.commit"
}

input_audio_buffer.clear

説明：WebSocket アクセス時は、push-to-talk モードでのみ有効です。 バッファー内の未コミットの音声を消去します。server_vad / smart_turn / smart_turn_v2 モードでは、このイベントは無視されます。サーバーは input_audio_buffer.cleared イベントを返します。
typestring(必須)イベントタイプ。固定値：input_audio_buffer.clear。
{
    "type": "input_audio_buffer.clear"
}

conversation.item.create

説明：会話コンテキストに会話アイテムを挿入します。このイベントを使用して、過去のコンテキストやテキストコンテンツを挿入したり、Function Callingの結果を返したりできます。
item.id がすでに会話内に存在する場合、エラーが返され、アイテムは作成されません。
typestring(必須)イベントタイプ。固定値：conversation.item.create。previous_item_idstring (任意)新しいアイテムを挿入する位置の直前の会話アイテムを指定します。指定しない場合、アイテムは会話の末尾に追加されます。itemobject(必須)作成する会話アイテム。

プロパティ

idstring (任意)会話アイテムの一意識別子です。指定しない場合、サーバーが自動的に生成します。指定されたIDがすでに会話内に存在する場合は、エラーが返されます。typestring(必須)会話アイテムのタイプ。有効な値は以下の通りです。
  • message：通常の会話メッセージ。
  • function_call：関数呼び出しリクエストです。通常はサーバーによって生成されますが、クライアントが過去のコンテキストを挿入するために使用することもできます。
  • function_call_output：ツールの実行結果です。function_call を受信した後、クライアントはツールを実行し、このタイプを使用して結果を返します。
rolestring (message タイプに必須)メッセージのロール。有効な値：system、user、assistant。contentarray (message タイプに必須)メッセージコンテンツ要素のリストです。各要素には type フィールドと対応するデータフィールドが含まれます。
systeminput_text：システムメッセージ。必須フィールド：text。user
  • input_text：ユーザーのテキスト入力。必須フィールド：text。
  • input_audio：ユーザーの音声入力。必須フィールド：audio (Base64 エンコード)。
assistantoutput_text：アシスタントのテキスト出力。必須フィールド：text。
call_idstring（function_call / function_call_output タイプに必須）関数呼び出しの一意識別子で、リクエストと結果の相関付けに使用されます。namestring (function_call タイプに必須)呼び出す関数の名前。argumentsstring (function_call タイプに必須)JSON 文字列形式の関数呼び出しパラメータ。outputstring (function_call_output タイプに必須)JSON 文字列形式のツール実行結果。
ユーザーのテキストメッセージを挿入します。
{
    "type": "conversation.item.create",
    "previous_item_id": "item_xxx",
    "item": {
        "id": "my_item_001",
        "type": "message",
        "role": "user",
        "content": [
            {
                "type": "input_text",
                "text": "Please summarize our last conversation"
            }
        ]
    }
}
Function Calling の結果を返します。
{
    "type": "conversation.item.create",
    "item": {
        "type": "function_call_output",
        "call_id": "call_xxx",
        "output": "{\"temperature\":18,\"condition\":\"sunny\"}"
    }
}

conversation.item.retrieve

説明：サーバーに保存されている会話アイテムを取得します。応答内の音声タイプのコンテンツには、元の音声データではなく転写テキスト（transcript）のみが含まれます。
typestring(必須)イベントタイプ。固定値：conversation.item.retrieve。item_idstring(必須)取得する会話アイテムのIDです。サーバーは結果を conversation.item.retrieved イベントで返します。
{
    "type": "conversation.item.retrieve",
    "item_id": "item_xxx"
}

conversation.item.delete

説明：会話コンテキストから会話アイテムを削除します。サーバーは conversation.item.deleted イベントで削除を確認します。
typestring(必須)イベントタイプ。固定値：conversation.item.delete。item_idstring(必須)削除する会話アイテムの ID。
{
    "type": "conversation.item.delete",
    "item_id": "item_xxx"
}

response.create

説明：モデルの推論をトリガーします。動作はモードによって異なります。
  • プッシュトゥートークモード：手動で呼び出す必要があります。まず input_audio_buffer.commit でバッファリングされた音声をコミットするか、トリガー前に function_call_output 結果を返してください。応答の生成中は呼び出せません。
  • server_vad モード：通常はサーバーによって自動的にトリガーされます。応答が生成されていないときは、クライアントが手動で呼び出すこともできます。応答の生成中は呼び出せません。
  • smart_turn モード：次のユーザーターンの待機中に呼び出すことができます。アクティブなターン中（input_audio_buffer.speech_started と response.done の間）は呼び出せません。
オプションの response フィールドは、現在の推論ラウンドのセッションデフォルトを上書きします。Function Calling シナリオでは、クライアントが function_call_output を返した後に、このイベントが2回目の推論ラウンドをトリガーします。
server_vad および smart_turn モードでは、手動でトリガーされた推論も新しい発話によって中断される可能性があります。
typestring(必須)イベントタイプ。固定値：response.create。responseobject (任意)現在の推論ラウンドのセッションデフォルトを上書きします。指定しない場合は、現在のセッション設定が使用されます。
modalitiesarray (任意)現在のラウンドの出力モダリティを上書きします。有効な値は session.update modalities と同じです。voicestring (任意)現在のターンの TTS ボイスを上書きします。
{
    "type": "response.create",
    "response": {
        "modalities": ["audio", "text"]
    }
}

response.cancel

説明：現在の推論をキャンセルします。これまでに生成されたテキストはアイテムリストに保存されます。その後、サーバーは status=cancelled を含む response.done イベントを返します。 推論が進行中でない場合、エラーが返されます。
typestring(必須)イベントタイプ。固定値：response.cancel。
{
    "type": "response.cancel"
}