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
説明:接続確立後、このイベントを送信してデフォルトのセッション設定を更新します。変更したいフィールドのみを含めてください。省略されたフィールドは現在の値を維持します。いずれかのパラメータが無効な場合、サーバーはエラーを返します。すべてのパラメータが有効な場合、サーバーは変更を適用し、完全な設定を返します。
注記turn_detection は、最初の音声が送信される前(IDLE 状態)にのみ変更できます。
typestring(必須)イベントタイプ。固定値:session.update。
sessionobject(任意)セッション設定。
プロパティ
modalitiesarray(任意)モデルの出力モダリティ。有効な値:
-
["text"]テキストのみ。
-
["audio", "text"](デフォルト)テキストと音声の両方。
voicestring(任意)TTS 音声名です。デフォルトは、3.1 Plus/Flash の場合は longanqian_v3.1、3.0 Plus/Flash の場合は longanqian です。システム音声とクローン音声がサポートされています。最初の session.update でのみ設定可能で、以降の呼び出しでは無視されます。
- 3.1 Plus/Flash のシステム音声:
longanqian_v3.1、および 3.1 TTS Plus と Flash の音声リストの和集合をサポートします。完全な範囲については、音声の設定をご覧ください。 - 3.0 Plus/Flash のシステム音声:利用可能な値:
longanqian、longanlingxin、longanlingxi、longanxiaoxin、longanlufeng。 - クローン音声:音声クローニング API で音声を作成し、このパラメータを返された
voice_idに設定します。詳細については、音声の設定をご覧ください。
qwen-audio-3.1-realtime-plus または qwen-audio-3.1-realtime-flash に接続した後、最初の session.update で音声を設定します。例:
{
"type": "session.update",
"session": {
"voice": "longanqian_v3.1"
}
}
speech_ratefloat(任意)モデルの音声出力の話速を制御します。範囲:[0.5, 2.0]。デフォルト:1.0。値を小さくすると話速が遅くなり、値を大きくすると速くなります。qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash でサポートされています。
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(任意)入力音声の文字起こし設定です。
プロパティ
languagestring(任意)入力音声のソース言語です。qwen-audio-3.1-realtime-plus と qwen-audio-3.1-realtime-flash に適用されます。このフィールドを省略しても、インスタントホットワードは有効です。
有効な値:
zh:中国語en:英語ja:日本語ko:韓国語vi:ベトナム語th:タイ語id:インドネシア語ar:アラビア語fr:フランス語de:ドイツ語es:スペイン語pt:ポルトガル語ru:ロシア語it:イタリア語
corpusobject(任意)入力音声の文字起こしのインスタントホットワード設定です。qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、qwen-audio-3.1-realtime-plus、および qwen-audio-3.1-realtime-flash に適用されます。
プロパティ
vocabularyobjectホットワードを整数の重みにマッピングするオブジェクトです。通常のホットワードの重みは 1〜5 です。重みが大きいほど、その語が文字起こしに採用されやすくなります。重み 50 はスーパーホットワードを表します。1 回の更新で、スーパーホットワードを最大 50 語、ホットワード全体で最大 2,000 語まで指定できます。
同じセッションで別の vocabulary オブジェクトを送信すると、以前のリスト全体が置き換えられます。空のオブジェクト {} を送信すると、ホットワードが消去されます。
output_audioobject(任意)出力音声の設定です。qwen-audio-3.1-realtime-plus と qwen-audio-3.1-realtime-flash に適用されます。
プロパティ
languagestring(任意)出力音声のターゲット言語です。
このパラメータは音声合成(TTS)に適用されます。モデルはターゲット言語で音声を生成するよう最善を尽くしますが、これは保証されず、応答テキストの言語も変更されません。ターゲット言語のテキストを生成するには、プロンプトで要件を明示してください。例えば、instructions で応答言語を指定します。
有効な値:
zh:中国語en:英語fr:フランス語de:ドイツ語ja:日本語ko:韓国語ru:ロシア語pt:ポルトガル語th:タイ語id:インドネシア語vi:ベトナム語es:スペイン語it:イタリア語ar:アラビア語
max_history_turnsinteger(任意)単一のリクエストに含まれる会話ターン(質問と回答のペア)の最大数です。有効な値は 1〜50 です。デフォルト:20。
enable_searchboolean(任意)Web 検索を有効にするかどうかを指定します。デフォルト:false。有効にすると、モデルはリアルタイムのクエリに基づいて Web を検索するかどうかを判断します。
同じセッションで enable_search を true に設定し、tools を通じて Function Calling ツールを設定できます。
search_optionsobject(任意)Web 検索の設定です。このパラメータは、enable_search が true に設定されている場合にのみ有効になります。
プロパティ
enable_sourceboolean(任意)検索結果の出典を返すかどうかを指定します。出典を返すには、このパラメータを true に設定します。
toolsarray(任意)Function Calling 用のツール定義です。設定すると、モデルはユーザー入力に基づいてツールを呼び出すかどうかを判断します。
プロパティ
typestring(必須)固定値:function。
functionobjectプロパティ
namestring(必須)ツール関数の名前。
descriptionstring(任意)ツール関数の説明です。モデルはこれを使用して、ツールを呼び出すかどうかを判断します。
parametersobject(任意)ツール関数の入力パラメータの説明です。モデルはこれを使用して必要なパラメータを抽出します。関数がパラメータを取らない場合は、このフィールドを省略してください。
プロパティ
typestring(必須)固定値:object。
propertiesobject(任意)各パラメータの名前、データ型、説明を記述します。
requiredarray(任意)必須となるパラメータを指定します。
turn_detectionobject|null(任意)以下で説明するターン検出フィールドは、qwen-audio-3.1-realtime-plus、qwen-audio-3.1-realtime-flash、qwen-audio-3.0-realtime-plus、および qwen-audio-3.0-realtime-flash に適用されます。
ターン検出の設定です。プッシュトゥートークモードに切り替えるには、このフィールドを null に設定します。プッシュトゥートークモードでは、音声を手動でコミットし、推論を手動でトリガーする必要があります。このフィールドが指定されない場合、VAD はデフォルトパラメータで有効になります。
プロパティ
typestring(任意)VAD タイプ。有効な値:
server_vad(デフォルト):音響特徴に基づいて発話の開始と終了を検出し、自動的に推論をトリガーします。smart_turn:音響知覚と意味理解を組み合わせてターン境界を判断する、インテリジェントなターン検出モードです。「えーと」や「あのー」などのフィラー音は、新しいターンのトリガーやモデル再生の中断を引き起こしません。smart_turn_v2(推奨):smart_turnをベースに、複数話者がいる環境での会話コンテキストと対話意図をより適切に理解します。傍観者や無関係な発話による意図しない応答や中断を低減します。
thresholdfloat(任意)VAD 感度です。server_vad、smart_turn、および smart_turn_v2 に適用されます。値を小さくすると VAD 感度が上がり、かすかな音(背景雑音を含む)を発話として検出しやすくなります。値を大きくすると感度が下がり、検出のトリガーにはより明瞭で大きな発話が必要になります。
範囲:[-1.0, 1.0]。デフォルト:0.5。
silence_duration_msinteger(任意)発話終了後、モデル応答をトリガーするまでの最小無音時間(ミリ秒単位)です。server_vad モードでのみ有効です(smart_turn / smart_turn_v2 モードでは無視されます)。値を小さくすると応答が速くなりますが、短い休止中に誤トリガーが発生する可能性があります。
範囲:[200, 6000]。デフォルト:800。会話での推奨範囲:400-800。
voiceprint_audio_urlsarray(任意)smart_turn / smart_turn_v2 モードでのみ有効です。ターゲットユーザーの事前録音済み音声サンプルを指す、公開アクセス可能な URL のリストで、話者強調に使用されます。登録すると、モデルはデュプレックス会話中にターゲット話者をロックオンし、他の音声や背景雑音を効果的に無視します。最大 5 つの URL。音声フォーマットの要件:16kHz PCM または WAV。
重要このパラメータは、最初の session.update イベントでのみ設定できます。以降の session.update イベントでは無視されます。
基本設定
以下の例は qwen-audio-3.1-realtime-plus と qwen-audio-3.1-realtime-flash に適用され、システム音声 longanqian_v3.1 を明示的に選択しています。
{
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "longanqian_v3.1",
"speech_rate": 1.2,
"turn_detection": {
"type": "server_vad",
"threshold": 0.5,
"silence_duration_ms": 800
}
}
}
言語設定
言語設定(qwen-audio-3.1-realtime-plus / qwen-audio-3.1-realtime-flash)qwen-audio-3.1-realtime-plus または qwen-audio-3.1-realtime-flash に接続した後、以下の session.update イベントを送信すると、入力音声のソース言語を中国語、出力音声のターゲット言語を英語に設定できます。
{
"type": "session.update",
"session": {
"input_audio_transcription": {
"language": "zh"
},
"output_audio": {
"language": "en"
}
}
}
インスタントホットワード
{
"type": "session.update",
"session": {
"input_audio_transcription": {
"corpus": {
"vocabulary": {
"祺元": 50
}
}
}
}
}
Function Calling
Function Calling:
{
"type": "session.update",
"session": {
"modalities": [
"text",
"audio"
],
"voice": "longanqian_v3.1",
"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_v2",
"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、および smart_turn_v2 モードでは無視されます。
typestring(必須)イベントタイプ。固定値:input_audio_buffer.commit。
{
"type": "input_audio_buffer.commit"
}
input_audio_buffer.clear
説明:WebSocket アクセスの場合、このイベントはプッシュトゥートークモードでのみ有効です。バッファー内の未コミットの音声を消去します。このイベントは 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(required for message type)メッセージのロール。有効な値:system、user、assistant。
contentarray(required for message type)メッセージコンテンツ要素のリストです。各要素には type フィールドと対応するデータフィールドが含まれます。
ロール別にサポートされているコンテンツタイプ
input_text:システムメッセージ。必須フィールド:text。
input_text:ユーザーのテキスト入力。必須フィールド:text。input_audio:ユーザーの音声入力。必須フィールド:audio(Base64 エンコード)。
output_text:アシスタントのテキスト出力。必須フィールド:text。
call_idstring(required for function_call / function_call_output type)関数呼び出しの一意識別子で、リクエストと結果の関連付けに使用されます。
namestring(required for function_call type)呼び出す関数の名前。
argumentsstring(required for function_call type)JSON 文字列形式の関数呼び出しパラメータ。
outputstring(required for function_call_output type)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 の結果
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 / smart_turn_v2 モード:次のユーザーターンの待機中に呼び出すことができます。アクティブなターン中(
input_audio_buffer.speech_startedからresponse.doneまで)は呼び出せません。
オプションの response フィールドは、現在の推論ラウンドのセッションデフォルトを上書きします。Function Calling シナリオでは、クライアントが function_call_output を返した後、このイベントが 2 回目の推論ラウンドをトリガーします。
注記server_vad、smart_turn、および smart_turn_v2 モードでは、手動でトリガーされた推論も新しい発話によって中断される可能性があります。
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"
}