すべてのプロダクト
Search

このプロダクト

    Alibaba Cloud Model Studio:WebSocket接続の概要

    ドキュメントセンター

    Alibaba Cloud Model Studio:WebSocket接続の概要

    最終更新日:Sep 29, 2026

    WebSocketエンドポイント、認証、RealtimeおよびInferenceのインタラクションフロー、ならびにモデル固有のイベントについて説明します。

    前提条件

    • 対象のモデルまたはアプリケーションを有効化し、サポートされているリージョンを確認してください。
    • 使用するリージョンおよびワークスペースのAPIキーを取得してください。トークン認証を参照してください。
    • ワークスペース固有のドメインを使用する場合は、ワークスペースIDを取得してください。

    プロトコルの選択とサポートされているモデルについては、Realtime API概要を参照してください。

    リクエストヘッダー

    WebSocketハンドシェイクリクエストでAuthorizationを設定します。その他のヘッダーについては、対象モデルのパラメーターリファレンスに記載されているとおりに使用してください。

    ヘッダー

    必須

    説明

    Authorization

    はい

    APIキーをBearer <API_KEY>として渡します。

    user-agent

    いいえ

    クライアントを識別します。

    X-DashScope-WorkSpace

    モデル固有

    ワークスペースIDを指定します。使用方法については、モデル固有のヘッダーリファレンスを参照してください。

    X-DashScope-DataInspection

    モデル固有

    データ検査を設定します。サポートされている値と適用範囲については、モデル固有のヘッダーリファレンスを参照してください。

    エンドポイント

    wss://を使用し、対象モデルに合わせてAPIパスとモデル名の指定位置を選択してください。以下の表に、モデルごとの接続方法を示します。サポートされているモデルとリージョンについては、対応するモデルのドキュメントを参照してください。

    モデルファミリー

    APIパス

    モデル名の指定位置

    Qwen-Omni-Realtime

    		/api-ws/v1/realtime

    URLクエリパラメーターmodel

    Qwen-Audio-TTS/CosyVoice

    		/api-ws/v1/inference

    run-task内のpayload.model

    Qwen-TTS-Realtime

    		/api-ws/v1/realtime

    URLクエリパラメーターmodel

    Qwen-Audio-ASR/Fun-ASR/Paraformer

    		/api-ws/v1/inference

    run-task内のpayload.model

    Qwen-ASR-Realtime

    		/api-ws/v1/realtime

    URLクエリパラメーターmodel

    Qwen-Audio-Realtime

    		/api-ws/v1/realtime

    URLクエリパラメーターmodel

    Qwen-LiveTranslate-Realtime

    		/api-ws/v1/realtime

    URLクエリパラメーターmodel

    ワークスペース固有のドメイン：

    リージョン

    ワークスペース固有のドメイン

    中国（北京）

    		{WorkspaceId}.cn-beijing.maas.aliyuncs.com

    シンガポール

    		{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

    {WorkspaceId}をお使いのワークスペースIDに置き換えます。例：

    wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=qwen3.8-omni-flash-realtime
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference

    Qwen-TTS-Realtimeは、北京の公開ドメインdashscope.aliyuncs.comとシンガポールのdashscope-intl.aliyuncs.comもサポートしており、同じ/api-ws/v1/realtimeパスを使用します。APIキーはリージョンと一致している必要があります。

    一般的なインタラクションフロー

    /api-ws/v1/realtimeはセッションベースのプロトコルを使用し、/api-ws/v1/inferenceはタスクベースのプロトコルを使用します。

    リアルタイムプロトコル

    接続後、クライアントはsession.updateでセッションを設定し、session.updatedを待機してから入力を送信します。入力のコミット方法、応答のトリガー方法、およびセッションの終了方法は、対象モデルによって決まります。

    1. クライアント → Realtime API：Authorizationおよびmodelを使用してWebSocketハンドシェイクを行います。
    2. Realtime API → クライアント：HTTP 101およびsession.created。
    3. クライアント → Realtime API：session.update。Realtime API → クライアント：session.updated。
    4. 入出力ループで入力ブランチを選択します：オーディオの場合はクライアント → Realtime API：input_audio_buffer.append；Qwen-TTSテキスト入力の場合はクライアント → Realtime API：input_text_buffer.append。
    5. オプションの手動コミット：クライアント → Realtime API：入力タイプに応じてinput_audio_buffer.commitまたはinput_text_buffer.commitを選択します。
    6. 明示的な応答を必要とするモデルの場合、クライアント → Realtime API：response.create。
    7. Realtime API → クライアント：テキストイベント／response.audio.delta。
    8. ASR専用モデルを除くオプションの応答完了：Realtime API → クライアント：response.done。入出力ループは継続可能です。
    9. 終了イベントをサポートするモデルの場合、クライアント → Realtime API：session.finish；Realtime API → クライアント：session.finished。
    10. クライアント → Realtime API：WebSocket接続を閉じます。

    詳細な手順

    1. 接続：URLのmodelクエリパラメーターにモデルを指定し、リクエストヘッダーにAPIキーを含めます。ハンドシェイクが成功すると、サーバーからsession.createdが送信されます。
    2. セッションの設定：session.updateを送信して、サポートされているオーディオ形式、出力モダリティ、音声、または音声検出パラメーターを設定し、session.updatedを待機します。サポートされているセッションパラメーターについては、モデル固有のクライアントイベントリファレンスを参照してください。
    3. 入力の送信：Base64エンコードされたオーディオをinput_audio_buffer.appendで送信します。Qwen-TTSの場合は、input_text_buffer.appendでテキストを送信します。画像入力をサポートするモデルではinput_image_buffer.appendを使用します。モデルの画像およびオーディオのタイミング要件に従ってください。
    4. コミットと結果の受信：自動モードでは、サーバーが処理をトリガーします。手動モードでは、入力タイプに応じてinput_audio_buffer.commitまたはinput_text_buffer.commitを送信してください。response.createも必要かどうか、およびどの結果イベントを処理すべきかは、モデルによって異なります。以下の比較表を参照してください。
    5. セッションの終了：終了イベントをサポートするモデルの場合、session.finishを送信し、session.finishedと残りの結果を待機してください。その他のモデルの場合、結果を受信した後にWebSocketを閉じてください。response.doneは1つの応答の終了を示すものであり、接続の終了を示すものではありません。ASR専用モデルの場合、転写完了イベントが認識の終了を示します。

    推論プロトコル

    クライアントはrun-taskを送信し、task-startedを待機してから入力を送信します。音声認識ではバイナリオーディオフレームを使用し、音声合成ではcontinue-taskでテキストを送信します。入力が終了したら、finish-taskを送信してtask-finishedを待機してください。

    1. クライアント → Inference API：Authorizationを使用してWebSocketハンドシェイクを行います。
    2. Inference API → クライアント：HTTP 101。
    3. クライアント → Inference API：payload.modelおよびtask_idを指定してrun-taskを実行します。Inference API → クライアント：task-started。
    4. 入出力ループにおいて、音声認識ブランチではクライアントからInference APIへバイナリオディオフレームを送信します。Inference APIはresult-generatedをクライアントに返します。
    5. 音声合成ブランチにおいて、クライアント → Inference API：テキストおよびtask_idを指定してcontinue-taskを実行します。Inference API → クライアント：バイナリオディオフレームおよび提供されている場合はresult-generatedを返します。
    6. 入出力ループが終了すると、クライアント → Inference API：同じtask_idを使用してfinish-taskを実行します。
    7. Inference API → クライアント：残りの結果およびtask-finished。
    8. クライアント → Inference API：モデルがサポートする場合、接続を閉じるか再利用します。

    詳細な手順

    1. 接続：/api-ws/v1/inferenceを使用し、リクエストヘッダーにAPIキーを含めます。
    2. タスクの開始：run-taskを送信し、payload.modelにモデルを、入力形式などのパラメーターを指定します。一意のheader.task_idを生成し、task-startedを待機してください。
    3. 入力の送信と結果の受信：
      • 音声認識：バイナリオーディオフレームを送信し、result-generatedを通じて認識結果を受信します。
      • 音声合成：continue-taskのpayload.input.textにテキストを送信し、バイナリオーディオフレームを受信します。モデルによっては、result-generatedを通じてタイムスタンプなどの情報を返す場合もあります。
    4. タスクの完了：finish-taskを送信した後、task-finishedが届くまで残りの結果を受信し続けてください。同じタスクに対するすべてのrun-task、continue-task、およびfinish-taskイベントでは、同じheader.task_idを使用する必要があります。その後、接続を閉じるか、モデルがサポートしている場合は接続を再利用してください。

    モデル間の違い

    リアルタイムモデル

    以下の表に、入力のトリガーとセッションの終了についてまとめます。サポートされているすべてのVADタイプ、オーディオ形式、およびその他のパラメーター値については、モデル固有のイベントリファレンスを参照してください。

    モデル

    入力および応答のトリガー

    終了

    Qwen3.8-Omni / Qwen3.5-Omni

    VADモードでは応答が自動的にトリガーされます。Manualモードでは、input_audio_buffer.commitを送信した後にresponse.createを送信してください。

    結果を受信した後、接続を閉じます。

    Qwen-TTS-Realtime

    server_commitはテキストを自動的にコミットします。commitモードでは、input_text_buffer.commitを送信してください。response.createは不要です。

    		session.finish → session.finished

    Qwen-ASR-Realtime

    VADモードでは入力が自動的に処理されます。Manualモードでは、input_audio_buffer.commitを送信してください。response.createは不要です。

    		session.finish → session.finished

    Qwen-Audio-Realtime

    自動モードではサーバー側でターンを検出します。Manualモードでは、input_audio_buffer.commitを送信した後にresponse.createを送信してください。

    結果を受信した後、接続を閉じます。

    Qwen3.8-LiveTranslate

    output_modalitiesで出力モダリティを設定し、audio.input.turn_detectionでターン検出を設定します。オーディオをストリーミングし、入力が終了したらsession.finishを送信してください。

    		session.finish → session.finished

    Qwen3.5-LiveTranslate

    modalitiesとturn_detectionでセッションを設定します。Manualモードでは、input_audio_buffer.commitがresponse.createなしに応答をトリガーします。

    		session.finish → session.finished

    主な出力イベントを以下に示します。返されるイベントは、設定された出力モダリティによって異なります。

    モデル

    主な出力イベント

    Qwen-Omni-Realtime

    response.text.delta / response.audio_transcript.delta / response.audio.delta / response.done

    Qwen-TTS-Realtime

    response.audio.delta / response.done

    Qwen-ASR-Realtime

    conversation.item.input_audio_transcription.text / conversation.item.input_audio_transcription.completed

    Qwen-Audio-Realtime

    response.audio_transcript.delta / response.audio.delta / response.done

    Qwen3.8-LiveTranslate

    response.text.delta / response.audio_transcript.delta / response.audio.delta / response.done

    Qwen3.5-LiveTranslate

    response.text.text / response.audio_transcript.text / response.audio.delta / response.done

    注記翻訳イベント名はモデルバージョンによって異なります。Qwen3.8-LiveTranslateは.deltaを使用し、Qwen3.5-LiveTranslateは.textを使用します。たとえば、翻訳されたオーディオトランスクリプトは、それぞれresponse.audio_transcript.deltaとresponse.audio_transcript.textを使用します。

    推論モデル

    Qwen-Audio-TTS/CosyVoiceはrun-task → task-started → continue-task → finish-task → task-finishedタスクフローを使用します。Qwen-Audio-ASR/Fun-ASR/Paraformer音声認識では、task-startedの後にバイナリオーディオフレームを送信します。どちらのタイプも、タスクエラーをtask-failedで報告します。

    モデル固有の統合ガイド

    リアルタイムオムニ

    リアルタイム音声合成

    Qwen-Audio-TTS

    CosyVoice

    Qwen-TTS-Realtime

    Sambert

    リアルタイム音声認識

    Qwen-Audio-ASR-Message

    Qwen-Audio-ASR-Streaming

    Fun-ASR-Realtime

    Qwen-ASR-Realtime

    Paraformer

    リアルタイム音声会話

    Qwen-Audio-Realtime

    リアルタイム音声・動画翻訳

    Qwen-Livetranslate-Realtime

    エラー処理

    • ハンドシェイク失敗：HTTPステータスとエラーメッセージを使用して、エンドポイント、APIキー、ワークスペース、およびモデルの権限を確認してください。401/403の場合は、まず認証を確認してください。
    • モデルが利用できないか、有効化されていません：モデル名、サービスの有効化状態、およびリージョンを確認してください。
    • リアルタイムエラー：errorイベントを処理し、そのタイプとメッセージを確認してください。エラーメッセージに基づいて、リクエストのイベントタイプやパラメーターを調整してください。
    • 推論エラー：task-failedイベントはタスクが失敗したことを示します。原因についてはheader.error_codeとheader.error_messageを確認してください。

    設定を修正した後、またはネットワーク中断に対処した後は、再接続し、プロトコルに応じて新しいセッションを設定するか、新しいタスクを開始してください。エラーコードを参照してください。