语音合成CosyVoice iOS SDK

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

文本字符计算规则：

文本长度限制

• 一次性输入待合成文本：发送文本长度不得超过 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]	否	提供语言提示，仅cosyvoice-v3-flash、cosyvoice-v3-plus支持该功能。 在语音合成中有如下作用： 指定 TN（Text Normalization，文本规范化）处理所用的语言，影响数字、缩写、符号等的朗读方式（仅中文、英文生效）。 取值范围： zh：中文 en：英文 指定语音合成的目标语言（仅限复刻音色），帮助提升合成效果准确性，对英文、法语、德语、日语、韩语、俄语生效（无需填写中文）。须和声音复刻时使用的languageHints/language_hints一致。 取值范围： en：英文 fr：法语 de：德语 ja：日语 ko：韩语 ru：俄语 若设置的语言提示与文本内容明显不符（如为中文文本设置en），将忽略此提示，并依据文本内容自动检测语言。 注意：此参数为数组，但当前版本仅处理第一个元素，因此建议只传入一个值。
  instruction	string	否	设置提示词。仅cosyvoice-v3-flash、cosyvoice-v3-plus支持该功能。 在语音合成中有如下作用： 指定小语种（仅限复刻音色） 格式：“你会用<小语种>说出来。”（注意，结尾一定不要遗漏句号，使用时将“<小语种>”替换为具体的小语种，例如替换为德语）。 示例：“你会用德语说出来。” 支持的小语种：法语、德语、日语、韩语、俄语。 指定方言（仅限复刻音色） 格式：“请用<方言>表达。”（注意，结尾一定不要遗漏句号，使用时将“<方言>”替换为具体的方言，例如替换为广东话）。 示例：“请用广东话表达。” 支持的方言：广东话、东北话、甘肃话、贵州话、河南话、湖北话、江西话、闽南话、宁夏话、山西话、陕西话、山东话、上海话、四川话、天津话、云南话。 指定情感、场景、角色或身份等：仅部分默认音色支持该功能，且因音色而异，详情请参见音色列表

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 公式转语音。