リアルタイム音声合成のための Qwen-TTS Realtime API のクライアントイベント - Model Studio - Alibaba Cloud_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

このトピックでは、Qwen-TTS Realtime API のクライアントイベントについて説明します。

リファレンス：リアルタイム音声合成 - Qwen。

session.update

セッション構成を更新します。WebSocket 接続が確立された後、インタラクションの最初のステップとしてこのイベントを送信してください。このイベントを送信しない場合、システムはデフォルト構成を使用します。サーバーがこのイベントを正常に処理した後、確認として session.updated イベントを返します。

event_idstring(必須)

クライアントが生成する一意のイベント ID です。単一の WebSocket 接続セッション内で一意である必要があります。Universally Unique Identifier (UUID) の使用を強く推奨します。

typestring(必須)

イベントタイプです。session.update に設定します。

sessionobject(オプション)

セッション構成です。

プロパティ

voicestring(必須)

音声合成に使用する音声です。詳細については、「サポートされる音声」をご参照ください。

システム音声とカスタム音声がサポートされています。

システム音声：Qwen3-TTS-Instruct-Flash-Realtime、Qwen3-TTS-Flash-Realtime、および Qwen-TTS-Realtime モデルシリーズでのみ利用可能です。音声サンプルについては、「サポートされる音声」をご参照ください。
カスタム音声
- 音声クローン (Qwen) を使用してカスタマイズされた音声：Qwen3-TTS-VC-Realtime シリーズでのみ利用可能です。
- 音声デザイン (Qwen) を使用してカスタマイズされた音声：Qwen3-TTS-VD-Realtime シリーズでのみ利用可能です。

modestring(オプション)

インタラクションパターンです。有効な値は以下のとおりです。

server_commit (デフォルト)：サーバーが自動的に合成タイミングを判断し、レイテンシと品質のバランスを取ります。ほとんどのシナリオでこのパターンを推奨します。
commit：クライアントが手動で合成をトリガーします。このパターンは最低のレイテンシを実現しますが、文の整合性を管理する必要があります。

language_typestring(オプション)

合成オーディオの言語です。デフォルト値は Auto です。

Auto：テキストの言語が不明な場合や、複数の言語が混在している場合に使用します。モデルはテキスト内の異なる言語セグメントに対して自動的に発音をマッチングしますが、完全な精度は保証できません。
特定の言語：単一言語のテキストに使用します。言語を指定することで合成品質が大幅に向上し、通常は Auto よりも優れた結果が得られます。有効な値は以下のとおりです。
- Chinese
- English
- German
- Italian
- Portuguese
- Spanish
- Japanese
- Korean
- French
- Russian

response_formatstring(オプション)

モデルからのオーディオ出力フォーマットです。

サポートされるフォーマット：

pcm (デフォルト)
wav
mp3
opus

Qwen-TTS-Realtime (「サポートされるモデル」をご参照ください) は pcm のみをサポートします。

sample_rateinteger(オプション)

モデルからのオーディオ出力のサンプルレート (Hz) です。

サポートされるサンプルレート：

8000
16000
24000 (デフォルト)
48000

Qwen-TTS-Realtime (「サポートされるモデル」をご参照ください) は 24000 のみをサポートします。

speech_ratefloat(オプション)

オーディオの話速です。1.0 が通常速度です。1.0 未満は低速、1.0 より大きい値は高速になります。

デフォルト値：1.0

有効範囲：[0.5, 2.0]

Qwen-TTS-Realtime (「サポートされるモデル」をご参照ください) はこのパラメーターをサポートしません。

volumeinteger(オプション)

オーディオのボリュームです。

デフォルト値：50

有効範囲：[0, 100]

Qwen-TTS-Realtime (「サポートされるモデル」をご参照ください) はこのパラメーターをサポートしません。

pitch_ratefloat(オプション)

合成オーディオのピッチです。

デフォルト値：1.0

有効範囲：[0.5, 2.0]

Qwen-TTS-Realtime (「サポートされるモデル」をご参照ください) はこのパラメーターをサポートしません。

bit_rateinteger(オプション)

ビットレート (kbps) です。ビットレートが高いほどオーディオ品質が向上し、ファイルサイズも大きくなります。このパラメーターは、オーディオフォーマット (response_format) が opus に設定されている場合にのみ使用できます。

デフォルト値：128

有効範囲：[6, 510]

Qwen-TTS-Realtime (「サポートされるモデル」をご参照ください) はこのパラメーターをサポートしません。

instructionsstring(オプション)

命令を設定します。「リアルタイム音声合成 - Qwen」をご参照ください。

デフォルト値：なし。設定されていない場合、このパラメーターは効果を持ちません。

長さ制限：長さは 1600 トークンを超えてはなりません。

サポート言語：中国語と英語のみサポートされます。

適用範囲：この機能は Qwen3-TTS-Instruct-Flash-Realtime モデルシリーズでのみ利用可能です。

optimize_instructionsboolean(オプション)

instructions を最適化して、音声合成の自然さと表現力を向上させるかどうかを指定します。

デフォルト値：false

動作：true に設定すると、システムはセマンティクスを強化し、instructions の内容を再書き込みして、音声合成により適した内部命令を生成します。

適用シナリオ：高品質かつ詳細な音声表現が求められるシナリオでこの機能を有効にしてください。

依存関係：このパラメーターは instructions パラメーターが設定されていることを前提としています。instructions が空の場合、このパラメーターは効果を持ちません。

適用範囲：この機能は Qwen3-TTS-Instruct-Flash-Realtime モデルシリーズでのみ利用可能です。

{
    "event_id": "event_123",
    "type": "session.update",
    "session": {
        "voice": "Cherry",
        "mode": "server_commit",
        "language_type": "Chinese",
        "response_format": "pcm",
        "sample_rate": 24000,
        "instructions": "",
        "optimize_instructions": false
    }
}

input_text_buffer.append

合成対象のテキストをテキストバッファーに追加します。server_commit モードでは、テキストはサーバー側のテキストバッファーに追加されます。commit モードでは、テキストはクライアント側のテキストバッファーに追加されます。

event_idstring(必須)

クライアントが生成する一意のイベント ID です。単一の WebSocket 接続セッション内で一意である必要があります。UUID の使用を強く推奨します。

typestring(必須)

イベントタイプです。input_text_buffer.append に設定します。

textstring(必須)

合成対象のテキストです。

{
  "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
  "type": "input_text_buffer.append",
  "text": "Hello, I am Qwen."
}

input_text_buffer.commit

ユーザー入力テキストバッファーをコミットして、会話内に新しいユーザーメッセージアイテムを作成します。入力テキストバッファーが空の場合、このイベントによりエラーが発生します。server_commit モードでは、このイベントを送信すると、それまでに蓄積されたすべてのテキストが即座に合成され、サーバーはそれ以降テキストをキャッシュしません。commit モードでは、クライアントがテキストバッファーをコミットしてユーザーメッセージアイテムを作成する必要があります。入力テキストバッファーのコミットによって、モデルからの応答は生成されません。サーバーは input_text_buffer.committed イベントを返します。

event_idstring(必須)

クライアントが生成する一意のイベント ID です。単一の WebSocket 接続セッション内で一意である必要があります。UUID の使用を強く推奨します。

typestring(必須)

イベントタイプです。input_text_buffer.commit に設定します。

{
  "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
  "type": "input_text_buffer.commit"
}

input_text_buffer.clear

バッファー内のテキストをクリアします。サーバーは input_text_buffer.cleared イベントを返します。

event_idstring(必須)

クライアントが生成する一意のイベント ID です。単一の WebSocket 接続セッション内で一意である必要があります。UUID の使用を強く推奨します。

typestring(必須)

イベントタイプです。input_text_buffer.clear に設定します。

{
  "event_id": "event_2728",
  "type": "input_text_buffer.clear"
}

session.finish

クライアントは session.finish イベントを送信して、これ以上テキスト入力がないことをサーバーに通知します。サーバーは残りのオーディオを返した後、接続を閉じます。

event_idstring(必須)

クライアントが生成する一意のイベント ID です。単一の WebSocket 接続セッション内で一意である必要があります。UUID の使用を強く推奨します。

typestring(必須)

イベントタイプです。session.finish に設定します。

{
  "event_id": "event_2239",
  "type": "session.finish"
}