Qwen-Audio-TTS iOS SDK - 千问AI平台

NeoNui

架构特点：

单例模式：通过 [StreamInputTts get_instance] 获取全局唯一实例
回调驱动：通过 StreamInputTtsDelegate 协议接收事件和数据
JSON 配置：参数通过 JSON 字符串传递

使用流程

Qwen-Audio-TTS 支持一次性输入和流式输入两种调用方式。 一次性输入：适用于短文本合成、需要使用 SSML 标记语言的场景。

playStreamInputTts() 或 asyncPlayStreamInputTts() - 发送一段完整的待合成文本并开始语音合成。前者为同步请求，合成完成后返回；后者为异步请求，发起合成后立即返回
onStreamInputTtsDataCallback() - 接收音频数据
TTS_EVENT_SYNTHESIS_COMPLETE - 语音合成结束

流式输入：适用于实时对话、长文本"边说边合"的场景。此方式不支持 SSML 标记语言。

startStreamInputTts() - 初始化SDK，设置回调接口和连接参数
sendStreamInputTts() - 持续发送待合成文本
onStreamInputTtsDataCallback() - 接收音频数据
stopStreamInputTts() 或 asyncStopStreamInputTts() - 发送合成结束请求。前者为同步请求，等待合成完成后返回；后者为异步请求，发起请求后立即返回
TTS_EVENT_SYNTHESIS_COMPLETE - 语音合成结束

startStreamInputTts

启动流式语音合成任务，与服务端建立连接。 方法签名

- (int) startStreamInputTts:(const char *)ticket parameters:(const char *)parameters sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

参数说明

参数	类型	说明
`ticket`	`char*`	JSON字符串，包含鉴权、连接和调试参数。
`parameters`	`char*`	JSON字符串，包含语音合成的具体效果参数。
`sessionId`	`char*`	客户端指定的会话ID。若不传入，服务端将自动生成。
`logLevel`	NuiSdkLogLevel	控制SDK自身日志的打印级别。
`saveLog`	`BOOL`	是否保存本地日志。若为`YES`，须通过`debug_path`指定路径，并可通过`max_log_file_size`设置文件大小。

**ticket JSON示例：**以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
  "url": "wss://maas.qianwenaiapi.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}

ticket 参数说明

参数	类型	是否必须	说明
`url`	`string`	是	服务地址，固定为 `wss://maas.qianwenaiapi.com/api-ws/v1/inference`。
`apikey`	`string`	是	API Key。建议使用时效性短、安全性更高的临时API Key，以降低长期有效Key泄露的风险。
`device_id`	`string`	是	用于标识终端用户的唯一字符串，可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。
`complete_waiting_ms`	`int`	否	调用`stopStreamInputTts`接口后，等待合成完成事件（`TTS_EVENT_SYNTHESIS_COMPLETE`）的超时时间（毫秒）。默认值：10000。
`debug_path`	`string`	否	日志文件的存储路径。此参数仅在调用`startStreamInputTts`、`playStreamInputTts`或`asyncPlayStreamInputTts`接口时将`saveLog`设为YES时生效。此时必须设置日志文件路径，否则将报错。本地最多保留两个日志文件。
`max_log_file_size`	`int`	否	设定日志文件的最大字节数。此参数仅在调用`startStreamInputTts`、`playStreamInputTts`或`asyncPlayStreamInputTts`接口时将`saveLog`设为YES时生效。默认值：104857600（100 * 1024 * 1024 字节，即 100MiB）。
`log_track_level`	`int`	否	控制通过日志回调（`onStreamInputTtsLogTrackCallback`）对外发送的日志内容的过滤级别。默认值：2。取值范围： 0：LOG_LEVEL_VERBOSE 1：LOG_LEVEL_DEBUG 2：LOG_LEVEL_INFO 3：LOG_LEVEL_WARNING 4：LOG_LEVEL_ERROR 5：LOG_LEVEL_NONE（表示关闭此功能）注意：`log_track_level`与`logLevel`（通过`startStreamInputTts`、`playStreamInputTts`或`asyncPlayStreamInputTts`接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于`log_track_level`和`logLevel`的值，才会被回调。例如，`log_track_level`设为2 (INFO)，`logLevel`设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。

parameters JSON 示例：以下为 JSON 字符串示例，参数未完整列出。请按实际需求在编码时补充：

{
  "model": "qwen-audio-3.0-tts-flash",
  "voice": "longanlingxi",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1,
  "pitch": 1,
  "language_hints": ["zh"],
  "enable_ssml": false
}

parameters 参数说明

参数	类型	是否必须	说明
`model`	`string`	是	模型名称。
`voice`	`string`	是	语音合成所使用的音色。系统音色：参见Qwen-Audio-TTS音色列表复刻音色：通过声音复刻功能定制声音设计音色：通过声音设计功能定制
`format`	`string`	否	音频编码格式。取值范围： pcm wav mp3（默认） opus
`enable_audio_decoder`	`BOOL`	否	是否启用 SDK 内部解码器。默认值：`NO`。仅在音频编码格式为 opus 或 mp3 时生效。启用后，SDK 将 opus 或 mp3 音频数据解码为 PCM 数据后返回。
`volume`	`int`	否	音量。默认值：50。取值范围：[0, 100]。
`sample_rate`	`int`	否	音频采样率（Hz）。取值范围：8000, 16000, 22050（默认）, 24000, 44100, 48000。
`rate`	`float`	否	语速。默认值：1.0。取值范围：[0.5, 2.0]。
`pitch`	`float`	否	音调。默认值：1.0。取值范围：[0.5, 2.0]。
`bit_rate`	`int`	否	音频码率（kbps）。音频格式为mp3或opus时，支持通过`bit_rate`参数调整码率。默认值：32。取值范围：[6, 510]。
`enable_ssml`	`boolean`	否	是否开启SSML功能。默认值：false。 true：开启。 false：关闭。 SSML 的使用限制（支持的模型、音色和接口），请参见使用限制。
`word_timestamp_enabled`	`boolean`	否	是否开启字级别时间戳。默认值：false。仅在流式输出模式下可用。支持复刻音色；支持的系统音色请参见Qwen-Audio-TTS音色列表。 > 时间戳结果在`onStreamInputTtsEventCallback`的all_response中。
`seed`	`int`	否	生成时使用的随机数种子，使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下，使用相同的seed可复现相同的合成结果。默认值0。取值范围：[0, 65535]。
`language_hints`	`array[string]`	否	提示： - 此参数为数组，但当前版本仅处理第一个元素，因此建议只传入一个值。此参数用于指定语音合成的目标语言，该设置与声音复刻时的样本音频的语种无关。如需设置复刻任务的源语言，请参见声音复刻API参考。指定语音合成的目标语言，提升合成效果。当数字、缩写、符号等朗读方式或者小语种合成效果不符合预期时使用，例如：数字朗读方式不符合预期，“hello, this is 110”读成“hello, this is one one zero”而非“hello, this is 幺幺零” 符号朗读不准确，“@”读成“艾特”而非“at” 小语种合成效果差，合成不自然 zh：中文 en：英语 fr：法语 de：德语 ja：日语 ko：韩语 ru：俄语 pt：葡萄牙语 th：泰语 id：印尼语 vi：越南语 es：西班牙语 it：意大利语 ms：马来西亚语 fil：菲律宾语 ar：阿拉伯语
`instruction`	`string`	否	设置指令，用于控制方言、情感或角色等合成效果。使用说明请参见指令控制。
`enable_aigc_tag`	`boolean`	否	是否在生成的音频中添加AIGC隐性标识。设置为true时，会将隐性标识嵌入到支持格式（wav/mp3/opus）的音频中。默认值：false。
`aigc_propagator`	`string`	否	设置AIGC隐性标识中的 `ContentPropagator` 字段，用于标识内容的传播者。仅在 `enable_aigc_tag` 为 `true` 时生效。默认值：千问AI平台账号。
`aigc_propagate_id`	`string`	否	设置AIGC隐性标识中的 `PropagateID` 字段，用于唯一标识一次具体的传播行为。仅在 `enable_aigc_tag` 为 `true` 时生效。默认值：本次语音合成请求Request ID。
`hot_fix`	`object`	否	文本热修复配置，用于自定义指定词语的发音或对待合成文本进行替换。参数介绍： pronunciation：自定义发音。指定词语的拼音标注，用于纠正默认发音不准确的情况。 replace：文本替换。在语音合成前将指定词语替换为目标文本，替换后的文本将作为实际合成内容。示例：示例 1 请参见表格下方

示例 1（说明）：

"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}

sendStreamInputTts

发送待合成的文本，与 startStreamInputTts 搭配使用。在调用 startStreamInputTts 后，使用此接口持续发送文本。所有文本发送完毕后，需调用stopStreamInputTts或asyncStopStreamInputTts来结束发送。 方法签名

- (int) sendStreamInputTts:(const char *)text;

参数说明

参数	类型	说明
`text`	`char*`	待合成文本。不支持SSML。如果传入的文本包含SSML标签，这些标签将被当作普通文本读出，不会被解析。

stopStreamInputTts

同步接口，通知服务端文本已全部发送，并阻塞等待所有音频数据合成并收到 TTS_EVENT_SYNTHESIS_COMPLETE。阻塞等待的超时时间由参数 complete_waiting_ms 控制。 方法签名

- (int) stopStreamInputTts;

asyncStopStreamInputTts

异步接口，通知服务端文本已全部发送。调用后立即返回，合成在后台继续进行。通过 TTS_EVENT_SYNTHESIS_COMPLETE 判断合成是否完成。 方法签名

- (int) asyncStopStreamInputTts;

cancelStreamInputTts

立即中断与服务端的连接并终止当前合成任务。调用后不会再收到任何音频数据回调。 方法签名

- (int) cancelStreamInputTts;

playStreamInputTts

同步执行的一次性合成接口。该接口会发送文本并阻塞等待接收所有音频数据，直到合成完成后才返回。无需再调用stopStreamInputTts接口。该接口默认启用SSML，可通过parameters中的enable_ssml参数关闭。 方法签名

- (int) playStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

参数说明 ticket、parameters等参数与startStreamInputTts接口中的定义相同。

参数	类型	说明
`text`	`char*`	待合成文本。支持SSML。

asyncPlayStreamInputTts

此接口异步发送全部待合成文本。调用后立即返回，不等待合成数据。无需再调用stopStreamInputTts接口。该接口默认启用SSML，可通过parameters中的enable_ssml参数关闭。 方法签名

- (int) asyncPlayStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

参数说明 ticket、parameters等参数与startStreamInputTts接口中的定义相同。

参数	类型	说明
`text`	`char*`	待合成文本。支持SSML。

StreamInputTtsDelegate

Qwen-Audio-TTS 流式语音合成回调协议，用于接收合成事件、音频数据和日志。

onStreamInputTtsEventCallback：监听事件

方法签名

- (void)onStreamInputTtsEventCallback:(StreamInputTtsCallbackEvent)event taskId:(char*)taskid sessionId:(char*)sessionId ret_code:(int)ret_code error_msg:(char*)error_msg timestamp:(char*)timestamp all_response:(char*)all_response;

参数说明

参数	类型	说明
`event`	StreamInputTtsCallbackEvent	回调事件。
`taskid`	`char*`	语音合成任务ID。
`sessionId`	`char*`	会话ID。客户端传入则原样返回；未传入时由服务端生成。
`ret_code`	`int`	仅在出现 `TTS_EVENT_TASK_FAILED` 事件时有效。
`error_msg`	`char*`	错误信息，仅在事件 `TTS_EVENT_TASK_FAILED` 中有效。
`timestamp`	`char*`	合成结果的时间戳信息。
`all_response`	`char*`	完整的 JSON 字符串响应。可解析以获取所需数据。

onStreamInputTtsDataCallback：监听音频数据

合成过程中，SDK 会连续触发此回调，需在回调中获取音频数据。 方法签名

- (void)onStreamInputTtsDataCallback:(char*)buffer len:(int)len;

参数说明

参数类型说明

参数	类型	说明
`buffer`	`char*`	返回当前片段的音频数据，可用于：合成完整的音频文件并播放。通过支持流式播放的播放器实时播放。注意：对 mp3/opus 压缩格式，分段传输必须使用流式播放器，不能逐帧播放，否则可能解码失败。组装完整文件时需采用追加模式写入同一文件。对于 wav 和 mp3 格式，仅在第一次 `onStreamInputTtsDataCallback` 回调的数据中包含文件头，后续回调均为纯音频数据。处理时需将所有回调的 `buffer` 按顺序拼接。opus 格式的每一帧都是独立的 Ogg page，可直接拼接。
`len`	`int`	音频数据的长度（字节）。

buffer

char*

返回当前片段的音频数据，可用于：

合成完整的音频文件并播放。
通过支持流式播放的播放器实时播放。

注意：

对 mp3/opus 压缩格式，分段传输必须使用流式播放器，不能逐帧播放，否则可能解码失败。
组装完整文件时需采用追加模式写入同一文件。
对于 wav 和 mp3 格式，仅在第一次 onStreamInputTtsDataCallback 回调的数据中包含文件头，后续回调均为纯音频数据。处理时需将所有回调的 buffer 按顺序拼接。opus 格式的每一帧都是独立的 Ogg page，可直接拼接。

len int 音频数据的长度（字节）。

onStreamInputTtsLogTrackCallback：监听追踪日志

此回调用于接收 SDK 内部的详细日志，方便进行问题定位和调试。 方法签名

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

参数说明

参数	类型	说明
`level`	`NuiSdkLogLevel`	日志级别。
`log`	`char*`	日志内容。

StreamInputTtsCallbackEvent

Qwen-Audio-TTS 流式语音合成事件类型枚举。

事件	说明
`TTS_EVENT_SYNTHESIS_STARTED`	表示服务端已成功接收请求并开始处理。通常在此事件后，`onStreamInputTtsDataCallback`将很快开始返回第一批音频数据。
`TTS_EVENT_SENTENCE_SYNTHESIS`	语音合成运行过程中的信息，包括计费信息等。
`TTS_EVENT_SYNTHESIS_COMPLETE`	表示服务端已发送完全部音频数据，此后 `onStreamInputTtsDataCallback`将不会再被调用。收到此事件是数据流结束的明确信号。
`TTS_EVENT_TASK_FAILED`	表示任务失败。此时可从`onStreamInputTtsEventCallback`的all_response获得task_id、error_code、error_message用于判断具体错误。示例 1 请参见表格下方

示例 1（说明）：

{
  "header": {
      "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
      "event": "task-failed",
      "error_code": "InvalidParameter",
      "error_message": "[tts:]Engine return error code: 418",
      "attributes": {}
  },
  "payload": {}
}

NuiSdkLogLevel

SDK 日志级别枚举，用于控制日志输出。

级别	说明
0：LOG_LEVEL_VERBOSE	最详细的日志，包含所有调试信息。
1：LOG_LEVEL_DEBUG	调试级别日志。
2：LOG_LEVEL_INFO	常规信息级别日志（默认值）。
3：LOG_LEVEL_WARNING	警告级别日志。
4：LOG_LEVEL_ERROR	错误级别日志。
5：LOG_LEVEL_NONE	关闭日志输出。

示例代码

获取API Key：获取与配置 API Key。

当您需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时API Key。临时API Key拥有固定的60秒有效期，过期后需重新获取。

下载SDK并运行示例代码：
- 下载最新SDK整合包。
- 解压 ZIP 包，将其中的 nuisdk.framework 添加到工程。
- 在 Build Phases → Link Binary With Libraries 中添加 nuisdk.framework。
- 在 General → Frameworks, Libraries, and Embedded Content 中将 nuisdk.framework 设置为 Embed & Sign。
- 用 Xcode 打开示例工程。示例代码位于DashCosyVoiceStreamInputTTSViewController.m，替换 API Key 后体验功能。

调用方式

调用方式 说明

一次性输入待合成文本

调用方式	说明
一次性输入待合成文本	调用步骤：初始化 SDK 和播放器组件。按业务需求设置参数。调用 `playStreamInputTts`或`asyncPlayStreamInputTts`发送文本并开始语音合成。接收到 `TTS_EVENT_SYNTHESIS_COMPLETE` 回调，语音合成结束。适用场景：短文本合成需要使用 SSML 标记语言
流式输入待合成文本	调用步骤：初始化 SDK 和播放器组件。按业务需求设置参数。调用 `startStreamInputTts` 开始流式文本语音合成。调用 `sendStreamInputTts` 持续发送文本。在`onStreamInputTtsDataCallback`中，获取二进制音频数据。调用 `stopStreamInputTts` 或 `asyncStopStreamInputTts` 结束发送，等待合成完成。接收到 `TTS_EVENT_SYNTHESIS_COMPLETE` 回调，语音合成结束。适用场景：实时对话、长文本“边说边合” 此方式不支持 SSML 标记语言

调用步骤：

初始化 SDK 和播放器组件。

按业务需求设置参数。

调用 playStreamInputTts或asyncPlayStreamInputTts发送文本并开始语音合成。

接收到 TTS_EVENT_SYNTHESIS_COMPLETE 回调，语音合成结束。

适用场景：

短文本合成
需要使用 SSML 标记语言

流式输入待合成文本

调用步骤：

初始化 SDK 和播放器组件。

按业务需求设置参数。

调用 startStreamInputTts 开始流式文本语音合成。

调用 sendStreamInputTts 持续发送文本。

在onStreamInputTtsDataCallback中，获取二进制音频数据。

调用 stopStreamInputTts 或 asyncStopStreamInputTts 结束发送，等待合成完成。

接收到 TTS_EVENT_SYNTHESIS_COMPLETE 回调，语音合成结束。

适用场景：

实时对话、长文本“边说边合”
此方式不支持 SSML 标记语言

高级功能

SSML 标记语言

目的：通过在文本中嵌入 XML 标签，实现对发音、语速、停顿等细节的精确控制。 使用限制：仅支持一次性输入待合成文本（playStreamInputTts 或 asyncPlayStreamInputTts 接口），不支持流式输入待合成文本（sendStreamInputTts接口）。 使用方法：调用 playStreamInputTts 或 asyncPlayStreamInputTts 接口时，SDK 会自动启用 SSML，此时直接在 text 参数中传入包含 SSML 标签的文本即可。更多说明请参见 SSML 与 LaTeX。

数学表达式

目的：使模型能够正确朗读常见的数学公式和表达式。 使用方法：直接在 text 参数中传入包含 LaTeX 格式的数学表达式的文本即可。更多说明请参见 LaTeX 公式转语音。

​NeoNui

​使用流程

​startStreamInputTts

​sendStreamInputTts

​stopStreamInputTts

​asyncStopStreamInputTts

​cancelStreamInputTts

​playStreamInputTts

​asyncPlayStreamInputTts

​StreamInputTtsDelegate

​onStreamInputTtsEventCallback：监听事件

​onStreamInputTtsDataCallback：监听音频数据

​onStreamInputTtsLogTrackCallback：监听追踪日志

​StreamInputTtsCallbackEvent

​NuiSdkLogLevel

​示例代码

​调用方式

​高级功能

​SSML 标记语言

​数学表达式

NeoNui

使用流程

startStreamInputTts

sendStreamInputTts

stopStreamInputTts

asyncStopStreamInputTts

cancelStreamInputTts

playStreamInputTts

asyncPlayStreamInputTts

StreamInputTtsDelegate

onStreamInputTtsEventCallback：监听事件

onStreamInputTtsDataCallback：监听音频数据

onStreamInputTtsLogTrackCallback：监听追踪日志

StreamInputTtsCallbackEvent

NuiSdkLogLevel

示例代码

调用方式

高级功能

SSML 标记语言

数学表达式