语音合成CosyVoice Android SDK

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

文本字符计算规则：

文本长度限制

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

• 流式输入待合成文本：单次发送文本长度不得超过 20000 字符，且累计发送文本总长度不得超过 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	否	调用stop接口后，等待合成完成事件（STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE）的超时时间（毫秒）。 默认值：10000。
  debug_path	String	否	日志文件的存储路径。 此参数仅在调用startStreamInputTts、playStreamInputTts或asyncPlayStreamInputTts接口时将save_log设为true时生效。此时必须设置日志文件路径，否则将报错。 本地最多保留两个日志文件。
  max_log_file_size	int	否	设定日志文件的最大字节数。 此参数仅在调用startStreamInputTts、playStreamInputTts或asyncPlayStreamInputTts接口时将save_log设为true时生效。 默认值：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与log_level（通过startStreamInputTts、playStreamInputTts或asyncPlayStreamInputTts接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于log_track_level和log_level的值，才会被回调。例如，log_track_level设为2 (INFO)，log_level设为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"]
  }

• 参数说明

  参数	类型	是否必须	说明
  model	String	是	语音合成模型。 不同模型版本需要使用对应版本的音色： cosyvoice-v3.5-flash/cosyvoice-v3.5-plus：无系统音色，仅支持使用声音设计/复刻音色。 cosyvoice-v3-flash/cosyvoice-v3-plus：使用longanyang等音色。 cosyvoice-v2：使用longxiaochun_v2等音色。 cosyvoice-v1：使用longwan等音色。 完整音色列表请参见音色列表。
  voice	String	是	语音合成所使用的音色。 支持系统音色和复刻音色： 系统音色：参见音色列表。 复刻音色：通过声音复刻功能定制。使用复刻音色时，请确保声音复刻与语音合成使用同一账号。 使用声音复刻生成的复刻音色时，本请求的model参数值，必须与创建该音色时所用的模型版本（即target_model参数）完全一致。 声音设计音色：通过声音设计功能定制。使用声音设计音色时，请确保声音设计与语音合成使用同一账号。 使用声音设计生成的音色时，本请求的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]。 cosyvoice-v1模型不支持该参数。
  enable_ssml	boolean	否	是否开启SSML功能。 默认值：false。 true：开启。 false：关闭。
  word_timestamp_enabled	boolean	否	是否开启字级别时间戳。 默认值：false。 true：开启。 false：关闭。 该功能仅适用于cosyvoice-v3-flash、cosyvoice-v3-plus和cosyvoice-v2模型的复刻音色，以及音色列表中标记为支持的系统音色。 时间戳结果在INativeStreamInputTtsCallback的all_response中。
  seed	int	否	生成时使用的随机数种子，使合成的效果产生变化。在模型版本、文本、音色及其他参数均相同的前提下，使用相同的seed可复现相同的合成结果。 默认值0。 取值范围：[0, 65535]。 cosyvoice-v1不支持该功能。
  language_hints	String[]	否	指定语音合成的目标语言，提升合成效果。cosyvoice-v1不支持该功能。 当数字、缩写、符号等朗读方式或者小语种合成效果不符合预期时使用，例如： 数字朗读方式不符合预期，“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：越南语 注意：此参数为数组，但当前版本仅处理第一个元素，因此建议只传入一个值。 重要 此参数用于指定语音合成的目标语言，该设置与声音复刻时的样本音频的语种无关。如果您需要设置复刻任务的源语言，请参见CosyVoice声音复刻/设计API。
  instruction	String	否	设置指令，用于控制方言、情感或角色等合成效果。该功能仅适用于cosyvoice-v3.5-flash、cosyvoice-v3.5-plus和cosyvoice-v3-flash模型的复刻音色，以及音色列表中标记为支持Instruct的系统音色。 长度限制：100字符。 汉字（包括简/繁体汉字、日文汉字和韩文汉字）按2个字符计算，其他所有字符（如标点符号、字母、数字、日韩文假名/谚文等）均按 1个字符计算 使用要求（因模型而异）： cosyvoice-v3.5-flash和cosyvoice-v3.5-plus：可以输入任意指令控制合成效果（如情感、语速等） 重要 cosyvoice-v3.5-flash和cosyvoice-v3.5-plus无系统音色，仅支持使用声音设计/复刻音色。 指令示例： 请用非常激昂且高亢的语气说话，表现出获得重大成功后的狂喜与激动。 语速请保持中等偏慢，语气要显得优雅、知性，给人以从容不迫的安心感。 语气要充满哀伤与怀念，带有轻微的鼻音，仿佛正在诉说一段令人心碎的往事。 请尝试用气声说话，音量极轻，营造出一种在耳边亲密低语的神秘感。 语气要显得非常急躁且不耐烦，语速加快，句子之间的停顿要尽量缩短。 请模拟一位慈祥、温和的长辈，语速平稳，声音中要透出满满的关怀与爱意。 语气要充满讽刺和不屑，在关键词上加重读音，句尾语调略微上扬。 请用一种极度恐惧且颤抖的声音说话。 语气要像专业的新闻播音员一样，冷静、客观且字正腔圆，情绪保持中立。 语气要显得活泼俏皮，带着明显的笑意，让声音听起来充满朝气与阳光。 cosyvoice-v3-flash：需遵照如下要求 复刻音色：可使用任意自然语言控制语音合成效果。 指令示例： 请用广东话表达。（支持的方言：广东话、东北话、甘肃话、贵州话、河南话、湖北话、江西话、闽南话、宁夏话、山西话、陕西话、山东话、上海话、四川话、天津话、云南话。） 请尽可能非常大声地说一句话。 请用尽可能慢地语速说一句话。 请用尽可能快地语速说一句话。 请非常轻声地说一句话。 你可以慢一点说吗 你可以非常快一点说吗 你可以非常慢一点说吗 你可以快一点说吗 请非常生气地说一句话。 请非常开心地说一句话。 请非常恐惧地说一句话。 请非常伤心地说一句话。 请非常惊讶地说一句话。 请尽可能表现出坚定的感觉。 请尽可能表现出愤怒的感觉。 请尝试一下亲和的语调。 请用冷酷的语调讲话。 请用威严的语调讲话。 我想体验一下自然的语气。 我想看看你如何表达威胁。 我想看看你怎么表现智慧。 我想看看你怎么表现诱惑。 我想听听用活泼的方式说话。 我想听听你用激昂的感觉说话。 我想听听用沉稳的方式说话的样子。 我想听听你用自信的感觉说话。 你能用兴奋的感觉和我交流吗？ 你能否展示狂傲的情绪表达？ 你能展现一下优雅的情绪吗？ 你可以用幸福的方式回答问题吗？ 你可以做一个温柔的情感演示吗？ 能用冷静的语调和我谈谈吗？ 能用深沉的方法回答我吗？ 能用粗犷的情绪态度和我对话吗？ 用阴森的声音告诉我这个答案。 用坚韧的声音告诉我这个答案。 用自然亲切的闲聊风格叙述。 用广播剧博客主的语气讲话。 系统音色：指令必须使用固定格式和内容，详情请参见音色列表
  enable_aigc_tag	boolean	否	是否在生成的音频中添加AIGC隐性标识。设置为true时，会将隐性标识嵌入到支持格式（wav/mp3/opus）的音频中。 默认值：false。 仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。
  aigc_propagator	String	否	设置AIGC隐性标识中的 ContentPropagator 字段，用于标识内容的传播者。仅在 enable_aigc_tag 为 true 时生效。 默认值：阿里云UID。 仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。
  aigc_propagate_id	String	否	设置AIGC隐性标识中的 PropagateID 字段，用于唯一标识一次具体的传播行为。仅在 enable_aigc_tag 为 true 时生效。 默认值：本次语音合成请求Request ID。 仅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支持该功能。

NativeNui

INativeStreamInputTtsCallback：监听回调

default void onStreamInputTtsLogTrackCallback(Constants.LogLevel level, String log)

StreamInputTtsEvent：事件类型

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