Skip to main content

Qwen-Audio-Realtime Android SDK

Qwen-Audio-Realtime の Android SDK を使用してリアルタイム音声対話を実装し、リアルタイム音声入力と音声またはテキストの出力を利用できます。

接続と認証は、WebSocket アクセスをご覧ください。イベントフィールドと JSON の例は、クライアントイベントとサーバーイベントをご覧ください。 ユーザーガイド：モデルの紹介と選択のアドバイスについては、リアルタイム音声会話を参照してください。

クイックスタート

  1. APIキーを取得して設定します。
  2. SDKをダウンロードしてサンプルコードを実行します:
    • 最新のSDKパッケージをダウンロードします。
    • ZIPパッケージを抽出します。app/libsからAAR SDKを取得し、プロジェクトの依存関係に追加します。Android C++統合の場合、ZIPパッケージ内のandroid_libsとandroid_includeを使用して、動的ライブラリとヘッダーファイルを取得します。
    • Android Studioでプロジェクトを開きます。サンプルコードはDashQwenAudioChatActivity.javaにあります。APIキーを置き換えて、機能を試してください。

呼び出し手順

  1. SDKを初期化します。
  2. ユースケースに合わせてパラメータを設定します。initializeのparameters引数を使用して接続および制御パラメータを設定し、setParamsを使用して音声会話パラメータを設定します。
  3. startDialog を呼び出して会話を開始します。
  4. onNuiAudioStateChangedで、音声状態に基づいて録音デバイスを開始します。
  5. onNuiNeedAudioDataで録音データを継続的に供給するか、updateAudioを呼び出して録音データをアクティブにプッシュします。
  6. onNuiAssistEventCallbackで、モデルから返される音声を受信し続けます。
  7. イベントをリッスンし、onNuiEventCallback でイベント情報を取得します。
  8. stopDialogを呼び出して会話を停止し、EVENT_TRANSCRIBER_COMPLETEをリッスンして終了したことを確認します。
  9. 会話機能が不要になったら、releaseを呼び出してSDKリソースを解放します。

リクエストパラメータ

接続および制御パラメータ

initialize の parameters 引数にJSON文字列を渡します。 例：以下のJSON文字列には、すべてのパラメータがリストされているわけではありません。ユースケースに応じて必要に応じてパラメータを追加してください。 サンプルは qwen-audio-3.1-realtime-plus を使用します。モデルを変更する場合は、URL の model と音声対話パラメーターの nls_config.model の両方を変更してください。 
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=qwen-audio-3.1-realtime-plus",
  "apikey": "st-****",
  "device_id": "my_device_id",
  "service_mode": "1"
}
パラメータ
パラメータ型必須説明
urlStringはいサービスエンドポイント：
  • wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • 中国（北京）：wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
  • シンガポール: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime?model=<model_name>
置き換え {WorkspaceId} 実際の ワークスペースID.
apikeyStringはいAPI キー。
service_modeStringはいランタイムモード。リアルタイム音声会話の場合、このパラメータを "1" に設定します。
device_idStringはいエンドユーザーを識別する一意の文字列です。アプリ内ユーザーIDまたはクライアント生成のデバイス識別子を使用できます。このIDは主にログのトレースとトラブルシューティングに使用されます。
audio_update_manuallyStringいいえ音声データをアクティブにプッシュするかどうかです。デフォルト："false"。"true"に設定されており、SDKがAECやVADなどのデバイス上音声機能をサポートしている場合、それらの機能はデフォルトで有効になります。
workspaceStringいいえデバイス上リソースファイルの保存パスです。このパラメータは、audio_update_manuallyが"true"であり、AECやVADなどのデバイス上音声機能が有効になっている場合に必須です。
debug_pathStringいいえログファイルの保存パスです。このパラメータは、initializeでsave_logがtrueの場合にのみ有効になります。この場合、パスは必須です。SDKはローカルに最大2つのログファイルを保持します。
save_wavStringいいえdebug_pathの下にデバッグ音声を保存するかどうかです。デフォルト："false"。有効な値は"true"および"false"です。このパラメータは、save_logがtrueであり、かつdebug_pathも設定されている場合にのみ有効になります。
max_log_file_sizeintいいえバイト単位の最大ログファイルサイズです。このパラメータは、save_logがtrueの場合にのみ有効になります。デフォルト：104857600（100 × 1024 × 1024バイト、または100 MiB）。
log_track_levelintいいえonNuiLogTrackCallbackを通じて送信されるログのフィルターレベルです。デフォルト：2。有効な値：0（VERBOSE）、1（DEBUG）、2（INFO）、3（WARNING）、4（ERROR）、および5（NONE）。ログは、そのレベルがlog_track_levelとinitializeに渡されるlevelの両方以上の場合にのみ返されます。たとえば、log_track_levelが2（INFO）でlevelが3（WARNING）の場合、WARNING以上のレベルのログ（3以上の値）のみが返されます。
aec_paramsobjectいいえ高度なデバイス上AEC設定です。このオブジェクトは、audio_update_manuallyが"true"の場合にのみ有効になります。
aec_params.enable_aecbooleanいいえデバイス上AECを有効にするかどうかです。audio_update_manuallyが"true"であり、SDKがデバイス上AECをサポートしている場合、AECはデフォルトで有効になります。
aec_params.save_audiobooleanいいえデバイス上AECモジュールによって処理された音声を保存するかどうかです。save_wavが"true"であり、debug_pathが設定されている場合、この機能はデフォルトで有効になり、音声はdebug_pathの下に保存されます。
aec_params.enable_aec_data_callbackbooleanいいえonNuiAssistEventCallbackのEVENT_AEC_DATAを通じてAEC処理済みの音声を返すかどうかです。デフォルト：false。
vad_paramsobjectいいえ高度なデバイス上VAD設定です。このオブジェクトは、audio_update_manuallyが"true"の場合にのみ有効になります。
vad_params.enable_vadbooleanいいえデバイス上VADを有効にするかどうかです。audio_update_manuallyが"true"であり、SDKがデバイス上VADをサポートしている場合、VADはデフォルトで有効になります。
vad_params.save_audiobooleanいいえデバイス上VADモジュールによって処理された音声を保存するかどうかです。save_wavが"true"であり、debug_pathが設定されている場合、この機能はデフォルトで有効になり、音声はdebug_pathの下に保存されます。

音声会話パラメータ

setParams の params 引数にJSON文字列を渡します。 例：以下のJSON文字列には、すべてのパラメータがリストされているわけではありません。ユースケースに応じて必要に応じてパラメータを追加してください。 
{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}
パラメータ
トップレベルパラメータ型必須説明
service_typeintはい音声サービスタイプ。リアルタイム音声会話の場合、このパラメータを 4 に設定します。
nls_configobjectはいモデルの選択や会話の動作を含む、コアとなる音声会話の設定。
nls_config.modelstringはいモデル名です。qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、およびqwen-audio-3.0-realtime-flashモデルシリーズをサポートします。
nls_config.sr_formatstringはい入力オーディオ形式。pcm のみがサポートされています。デフォルトの形式は 16 kHz、16 ビット、モノラルPCMです。
nls_config.modalitiesstringいいえ出力モダリティの配列を含む文字列です。有効な値：
  • ["text"]: テキストのみを返します。
  • ["audio", "text"] (デフォルト): オーディオとテキストの両方を返します。
nls_config.voicestringいいえTTS音声です。デフォルトは、3.1 Plusの場合はlonganqian_v3.1、3.0 Plus/Flashの場合はlonganqianです。このパラメータは、最初のsession.updateでのみ設定でき、それ以降の値は無視されます。システム音声：longanqian、longanlingxin、longanlingxi、longanxiaoxin、およびlonganlufeng。音声クローンAPIを通じて作成されたクローンvoice_idを指定することもできます。音声設定を参照してください。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もサポートしています。
nls_config.enable_speech_emotionbooleanいいえ強化された感情表現を有効にするかどうかです。有効にすると、応答音声の感情の変化がより顕著になります。デフォルト：true。有効な値：trueおよびfalse。
nls_config.instructionsstringいいえセッション全体におけるモデルの役割、応答スタイル、および動作の好みを定義するシステム指示です。
nls_config.max_history_turnsintいいえリクエストで許可される過去の質問と回答のターンの最大数です。有効な値：1～50。デフォルト：20。
nls_config.toolsstringいいえFunction Callingツール定義の配列を含む文字列です。このパラメータを設定すると、モデルはユーザー入力に基づいてツールを呼び出すかどうかを決定します。各定義はtype（必須、functionに固定）と、name（必須）、description（オプション）、およびparameters（オプション）を含むfunctionオブジェクトを使用します。関数に引数がない場合は、parametersを省略します。
例：
[
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Queries weather information for a specified city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "City"
          }
        },
        "required": [
          "city"
        ]
      }
    }
  }
]
nls_config.turn_detectionstringいいえターン検出用のJSONオブジェクトを含む文字列です。省略した場合、セッションはプッシュトゥートークモードを使用し、音声がコミットされ、推論が手動でトリガーされます。設定されている場合、デュプレックス会話モードが有効になります。
nls_config.turn_detection.typestringいいえVADタイプです。server_vad（デフォルト）は音響特徴から発話境界を検出し、自動的に推論をトリガーします。smart_turnは音響信号と意味信号を組み合わせており、フィラー音などの意味内容を持たない音はターンを開始したり、モデルの再生を中断したりしません。
nls_config.turn_detection.thresholdfloatいいえVAD感度です。このパラメータはserver_vadにのみ適用され、smart_turnには影響しません。値が低いほど、VADは静かな音や背景ノイズに対して敏感になり、値が高いほど、より明瞭で大きな音声が求められます。有効な範囲：[-1.0, 1.0]。デフォルト：0.5。
nls_config.turn_detection.silence_duration_msintいいえ発話後のモデル応答がトリガーされるまでの最小無音期間（ミリ秒単位）です。このパラメータはserver_vadにのみ適用され、smart_turnには影響しません。値が低いほどレイテンシは短縮されますが、短い一時停止でトリガーされる可能性があります。有効な範囲：[200, 6000]。デフォルト：800。会話での推奨値：400～800。
nls_config.turn_detection.voiceprint_audio_urlsstringいいえターゲットスピーカー用の公開アクセス可能な事前録音済み音声URLの配列を含む文字列です。このパラメータはsmart_turnにのみ適用されます。デュプレックス会話では、モデルがターゲットスピーカーに集中し、他のスピーカーや背景ノイズを無視するのに役立ちます。最大5つのURLがサポートされています。音声は16 kHz PCMまたはWAVである必要があります。

主要API

NativeNui

initialize

音声会話SDKインスタンスを初期化します。SDKはシングルトンです。releaseを呼び出す前に、複数回初期化しないでください。 このメソッドはブロックされるため、非UIスレッドで呼び出してください。 メソッドシグネチャ 
public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
パラメータ

パラメータ

型

説明

callback

INativeNuiCallback

イベントおよびデータコールバックインターフェースの実装。

parameters

String

認証、接続、およびデバッグパラメータを含むJSON文字列です。接続および制御パラメータを参照してください。

level

Constants.LogLevel

SDK独自のログの出力レベルを制御します。

save_log

boolean

ローカルログを保存するかどうかです。trueに設定した場合、接続および制御パラメータのdebug_pathを通じてパスを指定し、オプションでmax_log_file_sizeを通じてファイルサイズを設定します。

setParams

JSON形式で音声会話パラメータを設定します。startDialogの前にこのメソッドを呼び出します。 メソッドシグネチャ 
public synchronized int setParams(String params)
パラメータ

パラメータ

型

説明

params

String

音声会話パラメータ。

startDialog

会話を開始します。 メソッドシグネチャ 
public synchronized int startDialog(VadMode vad_mode, String dialog_params)
パラメータ
パラメータ型説明
vad_modeVadModeVADモード。VadMode.TYPE_P2T に固定されています。
dialog_paramsString接続および制御パラメータのapikeyが一時的なAPIキーである場合、有効期限が切れた後にここで更新します。
JSON形式：
{
  "apikey": "st-****"
}

stopDialog

会話を終了します。このメソッドを呼び出すと、サーバーは最終的な会話結果を返し、タスクを終了します。 メソッドシグネチャ 
public synchronized int stopDialog();

cancelDialog

会話を即座に終了します。このメソッドを呼び出すと、サーバーが最終的な会話結果を返すのを待たずに、タスクがすぐに終了します。 メソッドシグネチャ 
public synchronized int cancelDialog();

updateAction

インタラクション中に会話アクションコマンドを送信し、会話コンテキストなどのランタイム動作を更新します。 メソッドシグネチャ 
public synchronized int updateAction(String params);
パラメータ
パラメータ型説明
paramsString会話コンテキストなどのランタイムの動作を更新するために使用されるJSON文字列。
params.typeString"action" に設定します。
params.commandStringランタイムコマンドです。有効な値：
  • function_call: 関数呼び出しリクエストを更新します。
  • play_start: オンデバイスAECが使用されている場合、オーディオの再生が開始されたことをSDKに通知します。
  • play_over: オンデバイスAECが使用されている場合、オーディオの再生が終了したことをSDKに通知します。
params.contextString関数呼び出しリクエストの更新。command が "function_call" の場合に使用されます。
params.context.typeStringイベントタイプです。このパラメータは、commandが"function_call"の場合に必須です。conversation.item.createは、過去のコンテキスト、補足テキスト、またはツール結果の会話アイテムを挿入します。conversation.item.createを送信した後、response.createを使用して別の推論をトリガーします。
params.context.itemobjectparams.context.type が conversation.item.create の場合に必須。作成する会話アイテム。
params.context.responseobjectparams.context.typeがresponse.createの場合はオプションです。この推論のセッションデフォルトを上書きします。省略した場合、現在のセッション設定が使用されます。
context.item パラメータ:
パラメータ型説明
idStringオプションの一意な会話アイテムIDです。省略した場合、サーバーが生成します。指定されたIDが既に存在する場合はエラーが返されます。
typeString必須のアイテムタイプです。有効な値：
  • message: 通常のメッセージ。
  • function_call：関数呼び出しリクエストです。このタイプは通常、サーバーによって生成されます。クライアントはこれを使用して過去のコンテキストを追加することもできます。
  • function_call_output：ツール実行結果です。function_callを受信した後、クライアントはツールを実行し、このタイプを使用して結果を書き戻します。
roleStringmessage に必須。有効な値: system、user、および assistant。
contentarraymessageに必須です。各アイテムにはtypeと関連するデータフィールドが含まれます。systemはtextを持つinput_textをサポートし、userはtextを持つinput_textおよびBase64エンコードされたaudioを持つinput_audioをサポートし、assistantはtextを持つoutput_textをサポートします。
call_idStringfunction_callおよびfunction_call_outputに必須です。関数呼び出しリクエストとその結果を関連付ける一意のIDです。
nameStringfunction_call に必須。呼び出す関数の名前。
argumentsStringfunction_call に必須。JSON文字列としての関数の引数。
outputStringfunction_call_output に必須。JSON文字列としてのツール実行結果。
context.response パラメータ:
パラメータ型説明
modalitiesarray出力モダリティです。["text"]はテキストのみを返します。["audio", "text"]（デフォルト）は音声とテキストの両方を返します。
voicestringこの推論のTTS音声をオーバーライドします。
例: 
{
  "type": "action",
  "command": "function_call",
  "context": {
    "item": {
      "call_id": "call_xxxx",
      "output": "{\"city\":\"Hangzhou\",\"condition\":\"sunny\",\"temperature\":18}",
      "type": "function_call_output"
    },
    "type": "conversation.item.create"
  }
}

{
  "type": "action",
  "command": "function_call",
  "context": {
    "response": {
      "modalities": ["text", "audio"]
    },
    "type": "response.create"
  }
}

updateAudio

audio_update_manuallyが"true"に設定されている場合、onNuiNeedAudioDataを通じてデータを供給する代わりに、このメソッドを呼び出して録音データをアクティブにプッシュします。 メソッドシグネチャ 
public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);
パラメータ

パラメータ

型

説明

data

byte[]

プッシュするオーディオデータ。

len

int

プッシュするオーディオデータのバイト数。

first_pack

boolean

このパラメータは無視してください。

updateRefAudio

audio_update_manuallyが"true"に設定されており、デバイス上AECが有効になっている場合、このメソッドを呼び出して、プレーヤーで再生される音声を参照信号としてプッシュします。 メソッドシグネチャ 
public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);
パラメータ

パラメータ

型

説明

data

byte[]

プッシュするオーディオデータ。

len

int

プッシュするオーディオデータのバイト数。

first_pack

boolean

このパラメータは無視してください。

release

SDKのすべての内部リソースを解放します。このメソッドを呼び出すと、SDKインスタンスは使用できなくなります。再度使用するには、initializeを呼び出して再初期化する必要があります。 メソッドシグネチャ 
public synchronized int release();

GetVersion

現在のSDKバージョン情報を取得します。 メソッドシグネチャ 
public synchronized String GetVersion();
戻り値 現在のSDKバージョン情報。

INativeNuiCallback: リスナーコールバック

onNuiEventCallback: イベント情報のリッスン

メソッドシグネチャ 
void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);
パラメータ

パラメータ

型

説明

event

NuiEvent

コールバックイベント。

resultCode

int

EVENT_ASR_ERROR イベントが発生した場合にのみ有効です。

arg2

int

予約済みパラメータ。

asrResult

AsrResult

音声認識結果。

kwsResult

KwsResult

音声ウェイクアップ機能。このパラメータを使用する必要はありません。

onNuiAudioStateChanged: オーディオ状態のリッスン

SDKは、このコールバックを使用して、録音の開始または停止のタイミングを通知します。 メソッドシグネチャ 
void onNuiAudioStateChanged(AudioState state);
AudioStateの状態

状態

説明

STATE_OPEN

インタラクションが開始されました。録音デバイスを開いて録音を開始できます。

STATE_PAUSE

インタラクションが停止しました。録音を停止できます。

STATE_CLOSE

SDKインスタンスがリリースされました。録音デバイスを完全に閉じることができます。

onNuiNeedAudioData: オーディオデータの供給

会話開始後、このコールバックは継続的にトリガーされます。このコールバックで音声データを供給します。audio_update_manuallyが"true"に設定されている場合、このコールバックを使用する必要はありません。 メソッドシグネチャ 
int onNuiNeedAudioData(byte[] buffer, int len);
パラメータ

パラメータ

型

説明

buffer

byte[]

格納するオーディオデータ。

len

int

格納するオーディオデータのバイト数。

戻り値 実際に格納されたバイト数。

onNuiAssistEventCallback：補助イベントとデータの受信

このコールバックは、SDKから補助イベントおよび関連データを受信します。 メソッドシグネチャ 
void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);
パラメータ

パラメータ

型

説明

event

int

NuiEventイベントです。

info

String

このパラメータは無視してください。

info_len

int

このパラメータは無視してください。

data

byte[]

モデルから返されたTTSオーディオなどの補助データ。

onNuiLogTrackCallback: トレースログのリッスン

このコールバックは、トラブルシューティングとデバッグに役立つSDKからの詳細な内部ログを受信します。 
default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent: イベントタイプ

イベント説明
EVENT_TRANSCRIBER_STARTEDタスクが正常に開始されました。
EVENT_VAD_STARTタスク開始直後にトリガーされます。これは、発話の開始が検出されたことを意味するものではありません。
EVENT_VAD_END発話の終わりが検出されました。
EVENT_ASR_PARTIAL_RESULT中間音声認識結果。
EVENT_ASR_ERROR音声会話中にエラーが発生しました。
EVENT_MIC_ERROR2秒連続でオーディオデータが受信されなかった場合にトリガーされます。
EVENT_SENTENCE_END文の終わりが検出され、完全な認識結果が返されました。
EVENT_TRANSCRIBER_COMPLETE音声会話が終了しました。
EVENT_AUDIO_TRANSCRIPTION音声出力の増分テキスト転記イベントです。転記セグメントはストリーミングモードで返されます。
EVENT_AUDIO_TRANSCRIPTION_COMPLETEDオーディオ出力のトランスクリプトが完了しました。
EVENT_OTHER_RESULTFunction Callingの結果などのその他のイベント情報。
EVENT_ASR_TTS_STARTモデルがTTSオーディオの返送を開始しました。
EVENT_ASR_TTS_DATAモデルから返されたTTSオーディオ。
EVENT_ASR_TTS_COMPLETEモデルがTTSオーディオの返送を完了しました。
EVENT_AEC_DATAAECによって処理されたオーディオデータ。