语音合成CosyVoice iOS SDK

在资源与预算允许的情况下，优先选择 cosyvoice-v3-plus 获取最佳合成效果，对成本敏感时可选 cosyvoice-v3 平衡质量与价格，其余版本仅建议在兼容或低要求场景使用。

文本字符计算规则：

• 汉字：2字符

• 英文字母/数字/标点/空格：1字符

• 计算文本长度时，SSML标签内容也包含在内

• 示例：

  • "你好" → 2(你)+2(好)=4字符

  • "中A文123" → 2(中)+1(A)+2(文)+1(1)+1(2)+1(3)=8字符

  • "中文。" → 2(中)+2(文)+1(。)=5字符

  • "中 文。" → 2(中)+1(空格)+2(文)+1(。)=6字符

  • "<speak>你好</speak>" → 7(<speak>)+2(你)+2(好)+8(</speak>)=19字符

更多说明：限流、功能特性

文本长度限制

• 一次性输入待合成文本：发送文本长度不得超过 2000 字符。

• 流式输入待合成文本：单次发送文本长度不得超过 2000 字符，且累计发送文本总长度不得超过 20 万字符。

调用方式

连接与控制参数

通过在startStreamInputTts、playStreamInputTts和asyncPlayStreamInputTts接口的ticket参数中传入一个JSON字符串来配置。

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

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

• 参数说明

  参数	类型	是否必须	说明
  url	string	是	服务地址，固定为 wss://dashscope.aliyuncs.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）的日志才会被回调。

语音合成效果参数

通过在startStreamInputTts、playStreamInputTts和asyncPlayStreamInputTts接口的parameters参数中传入一个JSON字符串来配置。

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

  {
      "model": "cosyvoice-v2",
      "voice": "longxiaochun_v2",
      "format": "mp3",
      "sample_rate": 24000,
      "volume": 50,
      "rate": 1,
      "pitch": 1,
      "language_hints": ["zh"],
      "enable_ssml": false
  }

• 参数说明

  参数	类型	是否必须	说明
  model	string	是	语音合成模型。
  voice	string	是	音色。 默认音色：参见音色列表章节。 专属音色：通过声音复刻功能定制，须与调用本API所使用的阿里云账号为同一账号。 说明 使用声音复刻生成的专属音色时，本请求的model参数值，必须与创建该音色时所用的模型版本（即target_model参数）完全一致。
  format	string	否	音频编码格式。 默认值：mp3。 取值范围：pcm/wav/mp3/opus（当 model 为 cosyvoice-v1 时，不支持 opus 格式）。
  volume	int	否	音量。 默认值：50。 取值范围：[0, 100]。50代表标准音量。音量大小与该值呈线性关系，0为静音，100为最大音量。
  sample_rate	int	否	采样率（单位Hz）。 默认值：22050。 取值范围：8000/16000/22050/24000/44100/48000。
  rate	float	否	语速。 默认值：1.0。 取值范围：[0.5, 2.0]。1.0为标准语速，小于1.0则减慢，大于1.0则加快。
  pitch	float	否	音高。该值作为音高调节的乘数，但其与听感上的音高变化并非严格的线性或对数关系，建议通过测试选择合适的值。 默认值：1.0。 取值范围：[0.5, 2.0]。1.0为音色自然音高。大于1.0则音高变高，小于1.0则音高变低。
  bit_rate	int	否	音频码率（单位kbps）。音频格式为opus时，支持通过bit_rate参数调整码率。 默认值：32。 取值范围：[6, 510]。
  enable_ssml	boolean	否	是否开启SSML功能。 默认值：false。 true：开启。 false：关闭。
  word_timestamp_enabled	boolean	否	是否开启字级别时间戳。 默认值：false。 true：开启。 false：关闭。 仅cosyvoice-v2支持该功能。 时间戳结果在onStreamInputTtsEventCallback的all_response中。
  seed	int	否	生成时使用的随机数种子，使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下，使用相同的seed可复现相同的合成结果。 默认值0。 取值范围：[0, 65535]。 cosyvoice-v1不支持该功能。
  language_hints	array[string]	否	合成文本语言提示，可选值为 zh（中文）或 en（英文）。 仅cosyvoice-v3、cosyvoice-v3-plus支持该功能。 此设置会影响阿拉伯数字等内容的读法。例如，当合成“123”时，若设置为zh，则读作“一百二十三”；而en则会读作“one hundred and twenty-three”。 若设置的语言提示与文本内容明显不符（如为中文文本设置en），将忽略此提示，并依据文本内容自动检测语言。 注意：此参数为数组，但当前版本仅处理第一个元素，因此建议只传入一个值。
  instruction	string	否	提示词。 仅cosyvoice-v3默认音色支持该功能，声音复刻暂不支持。 目前仅支持设置情感。 格式：“你说话的情感是[情感值]。”（注意，结尾一定不要遗漏句号）。 支持的情感值：neutral、fearful、angry、sad、surprised、happy、disgusted。

StreamInputTts

StreamInputTtsDelegate：监听回调

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

StreamInputTtsCallbackEvent：事件类型

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

SSML 标记语言

目的：通过在文本中嵌入 XML 标签，实现对发音、语速、停顿等细节的精确控制。

使用限制：

• 模型：仅适用于 cosyvoice-v2 模型。

• 调用方式：仅支持一次性输入待合成文本（playStreamInputTts 或 asyncPlayStreamInputTts 接口），不支持流式输入待合成文本（sendStreamInputTts接口）。

使用方法：调用 playStreamInputTts 或 asyncPlayStreamInputTts 接口时，SDK 会自动启用 SSML，此时直接在 text 参数中传入包含 SSML 标签的文本即可。

详细的标签用法参考 SSML标记语言介绍。

数学表达式

目的：使模型能够正确朗读常见的数学公式和表达式。

使用限制：仅适用于 cosyvoice-v2 模型。

使用方法：直接在 text 参数中传入包含 LaTeX 格式的数学表达式的文本即可。详情参见 LaTeX 公式转语音。

当前默认支持的音色如下表所示。若您需要更加个性化的音色，可通过声音复刻功能免费定制专属音色，详情请参见使用复刻的音色进行语音合成。

进行语音合成时，model参数必须与所选音色对应，否则调用将失败。

待合成文本（text）应使用与所选音色语种一致的语言，否则可能出现发音错误或不自然