Qwen-Audio-Realtime iOS SDK

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

クイックスタート

API キーの取得: API キーの取得と設定。
SDKをダウンロードしてサンプルコードを実行します:
- 最新のSDKパッケージをダウンロードします。
- ZIP パッケージを抽出し、nuisdk.xcframework をプロジェクトに追加します。
- Build Phases > Link Binary With Libraries で、nuisdk.xcframework を追加します。
- General > Frameworks, Libraries, and Embedded Contentで、nuisdk.xcframeworkをEmbed & Signに設定します。
- Xcodeでプロジェクトを開きます。サンプルコードはDashQwenAudioChatViewController.mにあります。APIキーを置き換えて、機能を試してください。

呼び出し手順

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

リクエストパラメータ

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

nui_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"
}

パラメータ

パラメータ	型	必須	説明
`url`	`String`	はい	サービスエンドポイント： `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.
`apikey`	`String`	はい	API キー。
`service_mode`	`String`	はい	ランタイムモード。リアルタイム音声会話の場合、このパラメータを `"1"` に設定します。
`device_id`	`String`	はい	エンドユーザーを識別する一意の文字列です。アプリ内ユーザーIDまたはクライアント生成のデバイス識別子を使用できます。このIDは主にログのトレースとトラブルシューティングに使用されます。
`audio_update_manually`	`String`	いいえ	音声データをアクティブにプッシュするかどうかです。デフォルト：`"false"`。`"true"`に設定されており、SDKがAECやVADなどのデバイス上音声機能をサポートしている場合、それらの機能はデフォルトで有効になります。
`workspace`	`String`	いいえ	デバイス上リソースファイルの保存パスです。このパラメータは、`audio_update_manually`が`"true"`であり、AECやVADなどのデバイス上音声機能が有効になっている場合に必須です。
`debug_path`	`String`	いいえ	ログファイルの保存パスです。このパラメータは、`nui_initialize`で`save_log`が`true`の場合にのみ有効になります。この場合、パスは必須です。SDKはローカルに最大2つのログファイルを保持します。
`save_wav`	`String`	いいえ	`debug_path`の下にデバッグ音声を保存するかどうかです。デフォルト：`"false"`。有効な値は`"true"`および`"false"`です。このパラメータは、`save_log`が`true`であり、かつ`debug_path`も設定されている場合にのみ有効になります。
`max_log_file_size`	`int`	いいえ	バイト単位の最大ログファイルサイズです。このパラメータは、`save_log`が`true`の場合にのみ有効になります。デフォルト：`104857600`（100 × 1024 × 1024バイト、または100 MiB）。
`log_track_level`	`int`	いいえ	`onNuiLogTrackCallback`を通じて送信されるログのフィルターレベルです。デフォルト：`2`。有効な値：`0`（VERBOSE）、`1`（DEBUG）、`2`（INFO）、`3`（WARNING）、`4`（ERROR）、および`5`（NONE）。ログは、そのレベルが`log_track_level`と`nui_initialize`に渡される`level`の両方以上の場合にのみ返されます。たとえば、`log_track_level`が`2`（INFO）で`level`が`3`（WARNING）の場合、WARNING以上のレベルのログ（`3`以上の値）のみが返されます。

音声会話パラメータ

nui_set_params の params 引数に JSON 文字列を渡します。例：以下のJSON文字列には、すべてのパラメータがリストされているわけではありません。ユースケースに応じて必要に応じてパラメータを追加してください。

{
  "service_type": 4,
  "nls_config": {
    "model": "qwen-audio-3.1-realtime-plus",
    "sr_format": "pcm"
  }
}

パラメータ

トップレベルパラメータ	型	必須	説明
`service_type`	`int`	はい	音声サービスタイプ。リアルタイム音声会話の場合、このパラメータを `4` に設定します。
`nls_config`	`object`	はい	モデルの選択や会話の動作を含む、コアとなる音声会話の設定。
`nls_config.model`	`string`	はい	モデル名です。`qwen-audio-3.1-realtime-plus`、`qwen-audio-3.0-realtime-plus`、および`qwen-audio-3.0-realtime-flash`モデルシリーズをサポートします。
`nls_config.sr_format`	`string`	はい	入力オーディオ形式。`pcm` のみがサポートされています。デフォルトの形式は 16 kHz、16 ビット、モノラルPCMです。
`nls_config.modalities`	`string`	いいえ	出力モダリティの配列を含む文字列です。有効な値： `["text"]`: テキストのみを返します。 `["audio", "text"]` (デフォルト): オーディオとテキストの両方を返します。
`nls_config.voice`	`string`	いいえ	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_emotion`	`BOOL`	いいえ	強化された感情表現を有効にするかどうかです。有効にすると、応答音声の感情の変化がより顕著になります。デフォルト：`YES`。有効な値：`YES`および`NO`。
`nls_config.instructions`	`string`	いいえ	セッション全体におけるモデルの役割、応答スタイル、および動作の好みを定義するシステム指示です。
`nls_config.max_history_turns`	`int`	いいえ	リクエストで許可される過去の質問と回答のターンの最大数です。有効な値：1～50。デフォルト：`20`。
`nls_config.tools`	`string`	いいえ	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_detection`	`string`	いいえ	ターン検出用のJSONオブジェクトを含む文字列です。省略した場合、セッションはプッシュトゥートークモードを使用し、音声がコミットされ、推論が手動でトリガーされます。設定されている場合、デュプレックス会話モードが有効になります。
`nls_config.turn_detection.type`	`string`	いいえ	VADタイプです。`server_vad`（デフォルト）は音響特徴から発話境界を検出し、自動的に推論をトリガーします。`smart_turn`は音響信号と意味信号を組み合わせており、フィラー音などの意味内容を持たない音はターンを開始したり、モデルの再生を中断したりしません。
`nls_config.turn_detection.threshold`	`float`	いいえ	VAD感度です。このパラメータは`server_vad`にのみ適用され、`smart_turn`には影響しません。値が低いほど、VADは静かな音や背景ノイズに対して敏感になり、値が高いほど、より明瞭で大きな音声が求められます。有効な範囲：`[-1.0, 1.0]`。デフォルト：`0.5`。
`nls_config.turn_detection.silence_duration_ms`	`int`	いいえ	発話後のモデル応答がトリガーされるまでの最小無音期間（ミリ秒単位）です。このパラメータは`server_vad`にのみ適用され、`smart_turn`には影響しません。値が低いほどレイテンシは短縮されますが、短い一時停止でトリガーされる可能性があります。有効な範囲：`[200, 6000]`。デフォルト：`800`。会話での推奨値：`400`～`800`。
`nls_config.turn_detection.voiceprint_audio_urls`	`string`	いいえ	ターゲットスピーカー用の公開アクセス可能な事前録音済み音声URLの配列を含む文字列です。このパラメータは`smart_turn`にのみ適用されます。デュプレックス会話では、モデルがターゲットスピーカーに集中し、他のスピーカーや背景ノイズを無視するのに役立ちます。最大5つのURLがサポートされています。音声は16 kHz PCMまたはWAVである必要があります。

主要API

NeoNui

nui_initialize

音声会話SDKインスタンスを初期化します。SDKはシングルトンです。nui_releaseを呼び出す前に、再度初期化しないでください。 メソッドシグネチャ

-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;

パラメータの説明

パラメータ	型	説明
`parameters`	`char*`	認証、接続、およびデバッグパラメータを含む JSON 文字列。接続および制御パラメータを参照してください。
`level`	`NuiSdkLogLevel`	SDK 独自のログの出力レベル。
`save_log`	BOOL	ローカルにログを保存するかどうか。`YES`に設定した場合、接続および制御パラメータの`debug_path`でパスを指定し、必要に応じて`max_log_file_size`でファイルサイズを設定します。

nui_set_params

音声会話パラメータをJSON形式で設定します。nui_dialog_startの前にこのメソッドを呼び出します。 メソッドシグネチャ

-(NuiResultCode) nui_set_params:(const char *)params;

パラメータの説明

パラメータ	型	説明
`params`	`char*`	音声会話パラメータ。

nui_dialog_start

会話を開始します。 メソッドシグネチャ

-(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                      dialogParam:(const char *)dialog_params;

パラメータ

パラメータ	型	説明
`vad_mode`	`NuiVadMode`	VADモード。`MODE_P2T` に固定されています。
`dialog_params`	`char*`	接続および制御パラメータの`apikey`が一時的なAPIキーである場合、有効期限が切れた後にここで更新します。 JSON形式： `{ "apikey": "st-****" }`

nui_dialog_cancel

対話を終了するか、現在のインタラクションをすぐにキャンセルします。 メソッドシグネチャ

-(NuiResultCode) nui_dialog_cancel:(BOOL)force;

パラメータの説明

パラメータ	型	説明
`force`	`BOOL`	強制的に終了して最終結果を破棄するかどうか。 `YES`: サーバーが最終的な対話結果を返すのを待たずに、タスクをすぐに終了します。 `NO`: タスクを終了しますが、完全な結果が返されるのを待ちます。

パラメータ

型

説明

force

BOOL

強制的に終了して最終結果を破棄するかどうか。

YES: サーバーが最終的な対話結果を返すのを待たずに、タスクをすぐに終了します。
NO: タスクを終了しますが、完全な結果が返されるのを待ちます。

nui_dialog_action

インタラクション中に会話アクションコマンドを送信し、会話コンテキストなどのランタイム動作を更新します。 メソッドシグネチャ

- (NuiResultCode) nui_dialog_action:(const char *)params;

パラメータ

パラメータ	型	説明
`params`	`char*`	会話コンテキストなどのランタイムの動作を更新するために使用されるJSON文字列。
`params.type`	`String`	`"action"` に設定します。
`params.command`	`String`	ランタイムコマンドです。有効な値： `function_call`: 関数呼び出しリクエストを更新します。 `play_start`: オンデバイスAECが使用されている場合、オーディオの再生が開始されたことをSDKに通知します。 `play_over`: オンデバイスAECが使用されている場合、オーディオの再生が終了したことをSDKに通知します。
`params.context`	`String`	関数呼び出しリクエストの更新。`command` が `"function_call"` の場合に使用されます。
`params.context.type`	`String`	イベントタイプです。このパラメータは、`command`が`"function_call"`の場合に必須です。`conversation.item.create`は、過去のコンテキスト、補足テキスト、またはツール結果の会話アイテムを挿入します。`conversation.item.create`を送信した後、`response.create`を使用して別の推論をトリガーします。
`params.context.item`	`object`	`params.context.type` が `conversation.item.create` の場合に必須。作成する会話アイテム。
`params.context.response`	`object`	`params.context.type`が`response.create`の場合はオプションです。この推論のセッションデフォルトを上書きします。省略した場合、現在のセッション設定が使用されます。

context.item パラメータ:

パラメータ	型	説明
`id`	`String`	オプションの一意な会話アイテムIDです。省略した場合、サーバーが生成します。指定されたIDが既に存在する場合はエラーが返されます。
`type`	`String`	必須のアイテムタイプです。有効な値： `message`: 通常のメッセージ。 `function_call`：関数呼び出しリクエストです。このタイプは通常、サーバーによって生成されます。クライアントはこれを使用して過去のコンテキストを追加することもできます。 `function_call_output`：ツール実行結果です。`function_call`を受信した後、クライアントはツールを実行し、このタイプを使用して結果を書き戻します。
`role`	`String`	`message` に必須。有効な値: `system`、`user`、および `assistant`。
`content`	`array`	`message`に必須です。各アイテムには`type`と関連するデータフィールドが含まれます。`system`は`text`を持つ`input_text`をサポートし、`user`は`text`を持つ`input_text`およびBase64エンコードされた`audio`を持つ`input_audio`をサポートし、`assistant`は`text`を持つ`output_text`をサポートします。
`call_id`	`String`	`function_call`および`function_call_output`に必須です。関数呼び出しリクエストとその結果を関連付ける一意のIDです。
`name`	`String`	`function_call` に必須。呼び出す関数の名前。
`arguments`	`String`	`function_call` に必須。JSON文字列としての関数の引数。
`output`	`String`	`function_call_output` に必須。JSON文字列としてのツール実行結果。

context.response パラメータ:

パラメータ	型	説明
`modalities`	`array`	出力モダリティです。`["text"]`はテキストのみを返します。`["audio", "text"]`（デフォルト）は音声とテキストの両方を返します。
`voice`	`string`	この推論の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"
  }
}

nui_update_audio_data

audio_update_manuallyが"true"に設定されている場合、録音データはonNuiNeedAudioDataを通じて供給されなくなります。代わりに、このメソッドを使用してアクティブにプッシュしてください。 メソッドシグネチャ

-(NuiResultCode) nui_update_audio_data:(const char *)data
                                    Len:(int)length
                              FirstPack:(BOOL)first_pack;

パラメータの説明

パラメータ	型	説明
`data`	`const char *`	プッシュするオーディオデータ。
`length`	`int`	音声データの長さ (バイト単位)。
`first_pack`	`BOOL`	このパラメータを使用する必要はありません。

nui_push_reference_data

audio_update_manuallyが"true"に設定されており、デバイス上の音響エコーキャンセル（AEC）が有効になっている場合、このメソッドを使用してプレーヤーで再生されるオーディオを参照信号としてプッシュします。 メソッドシグネチャ

-(NuiResultCode) nui_push_reference_data:(const char *)data
                                     Len:(int)length
                               FirstPack:(BOOL)first_pack;

パラメータの説明

パラメータ	型	説明
`data`	`const char *`	プッシュするオーディオデータ。
`length`	`int`	音声データの長さ (バイト単位)。
`first_pack`	`BOOL`	このパラメータを使用する必要はありません。

nui_release

すべての内部SDKリソースを解放し、実行中のすべてのタスクを強制終了します。このメソッドを呼び出すと、SDKインスタンスは使用できなくなります。再度使用するには、nui_initializeを呼び出して再初期化する必要があります。 メソッドシグネチャ

-(NuiResultCode) nui_release;

nui_get_version

現在の SDK バージョンを取得します。このメソッドは nui_initialize が呼び出された後にのみ値を返します。 メソッドシグネチャ

-(const char*) nui_get_version;

戻り値 現在の SDK バージョン。

nui_get_all_response

現在のイベントコールバックの完全な情報を取得します。 メソッドシグネチャ

-(const char*) nui_get_all_response;

戻り値 JSON 文字列としての完全なイベント情報。

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

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

メソッドシグネチャ

-(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                    dialog:(long)dialog
                 kwsResult:(const char *)wuw
                 asrResult:(const char *)asr_result
                  ifFinish:(BOOL)finish
                   retCode:(int)code;

パラメータの説明

パラメータ	型	説明
`nuiEvent`	NuiCallbackEvent	コールバックイベント。
`dialog`	`long`	セッション ID。このパラメータを使用する必要はありません。
`wuw`	`char*`	音声ウェイクアップ。このパラメータを使用する必要はありません。
`asr_result`	`char*`	音声認識結果。
`finish`	`BOOL`	現在の認識ラウンドが終了したかどうか。
`code`	`int`	`EVENT_ASR_ERROR` イベントが発生した場合にのみ有効です。

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

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

-(void) onNuiAudioStateChanged:(NuiAudioState)state;

NuiAudioState の状態

パラメータ	説明
`STATE_OPEN`	インタラクションが開始されました。録音デバイスを開いて録音を開始できます。
`STATE_PAUSE`	インタラクションが停止しました。録音を停止できます。
`STATE_CLOSE`	SDK インスタンスがリリースされました。録音デバイスを完全に閉じることができます。

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

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

-(int) onNuiNeedAudioData:(char *)audioData length:(int)len;

パラメータの説明

パラメータ	型	説明
`audioData`	`char *`	供給する音声データ。
`len`	`int`	供給された音声データのサイズ (バイト単位)。

onNuiAssistEventCallback: 補助データと情報を受信する

SDK から補助イベントおよび関連データを受信します。 メソッドシグネチャ

-(void) onNuiAssistEventCallback:(NuiCallbackEvent)nuiEvent
                            info:(char*)info
                         infoLen:(int)info_len
                          buffer:(char*)buffer
                             len:(int)len;

パラメータの説明

パラメータ	型	説明
`nuiEvent`	`NuiCallbackEvent`	コールバックイベント。
`info`	`char *`	このパラメータを使用する必要はありません。
`info_len`	`int`	このパラメータを使用する必要はありません。
`buffer`	`char *`	モデルから返されたTTSオーディオなどの補助データ。
`len`	`int`	補助データの長さ (バイト単位)。

onNuiLogTrackCallback: トラッキングログをリッスンする

このコールバックは SDK の詳細な内部ログを受信し、問題の特定とデバッグを支援します。

-(void) onNuiLogTrackCallback:(NuiSdkLogLevel)level
                   logMessage:(const char *)log;

`NuiCallbackEvent`: イベントタイプ

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

​クイックスタート

​呼び出し手順

​リクエストパラメータ

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

​音声会話パラメータ

​主要API

​NeoNui

​nui_initialize

​nui_set_params

​nui_dialog_start

​nui_dialog_cancel

​nui_dialog_action

​nui_update_audio_data

​nui_push_reference_data

​nui_release

​nui_get_version

​nui_get_all_response

​NeoNuiSdkDelegate: コールバックリスナー

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

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

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

​onNuiAssistEventCallback: 補助データと情報を受信する

​onNuiLogTrackCallback: トラッキングログをリッスンする

​NuiCallbackEvent: イベントタイプ

クイックスタート

呼び出し手順

リクエストパラメータ

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

音声会話パラメータ

主要API

NeoNui

nui_initialize

nui_set_params

nui_dialog_start

nui_dialog_cancel

nui_dialog_action

nui_update_audio_data

nui_push_reference_data

nui_release

nui_get_version

nui_get_all_response

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

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

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

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

onNuiAssistEventCallback: 補助データと情報を受信する

onNuiLogTrackCallback: トラッキングログをリッスンする

`NuiCallbackEvent`: イベントタイプ