CosyVoice流式文本语音合成接口说明-智能语音交互(ISI)-阿里云帮助中心

功能与使用限制

支持PCM、WAV、MP3和OPUS音频编码格式。
在同一会话中，可以分批发送文本并接收音频。每批文本无需构成完整的单词或句子，服务端根据语义断句和重组文本。

实时播放音频时，使用支持流式播放的工具或组件，例如FFmpeg、PyAudio（Python）和MediaSource（JavaScript）。
同一会话中，单次合成不超过1万字符，累计不超过20万字符。1个汉字计为2个字符；1个英文字母、标点或句子中间的空格计为1个字符。
输入文本采用UTF-8编码。
支持设置语速、语调和音量，以及选择音色。这些配置需在开始合成前完成。

说明
使用SDK的startStreamInputTts方法时，需在调用前配置语速、语调、音量和声音风格。
使用支持时间戳的音色，并将enable_subtitle设为true，可以获取字级时间戳。
使用支持SSML的音色，并将enable_ssml设为true，可以使用SSML标记。此模式下，每个会话仅发送一次完整文本。
CosyVoice-V2支持中文LaTeX数学表达式。支持的语法和限制请参见LaTeX能力支持说明。

计费和并发限制

仅提供商用版，不支持试用。使用前需开通商用版，开通方式请参见升级为商用版。
费用涉及的计费项请参见计费项，计费方式请参见计费方式。
并发限制请参见并发和QPS说明。

服务地址与鉴权

根据网络环境选择服务地址，并将SDK的URL设为所选地址。

访问方式	适用条件	服务地址
外网访问	可以通过公网连接服务，SDK默认使用外网地址。	北京：`wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1`
ECS内网访问	使用北京地域（华北2）的ECS实例，通过专有网络（VPC）访问。经典网络不支持通过内网访问语音服务。	北京：`ws://nls-gateway-cn-beijing-internal.aliyuncs.com:80/ws/v1`

说明

使用内网访问方式，不产生ECS实例的公网流量费用。

建立WebSocket连接时，使用NLS Token进行鉴权。获取方式请参见获取Token。

交互流程

建立连接：客户端使用Token鉴权，建立WebSocket连接。
开始合成：发送StartSynthesis消息，指定Appkey、音色和其他合成参数。收到SynthesisStarted事件后，开始发送文本。
发送文本：通过RunSynthesis消息的payload.text发送待合成文本。流式输入时可以分批发送；开启SSML时，只发送一次完整文本。
接收音频：服务端返回语音二进制数据，客户端在发送文本的同时接收音频并按所选格式处理。
结束输入：文本全部发送后，发送StopSynthesis消息，通知服务端输入结束，并继续接收合成结果。
完成合成：收到SynthesisCompleted事件后，当前任务结束，可以关闭连接。任务失败时，服务端返回TaskFailed事件。

请求参数

合成配置

以下为StartSynthesis消息的配置参数，其中appkey位于header，其余参数位于payload。使用SDK时，通过对应的参数设置方法配置；例如，StreamInputTts对象提供set方法。

参数	类型	是否必选	说明
`appkey`	String	是	项目的Appkey，可在智能语音交互控制台获取。
`voice`	String	是	音色名称，取值请参见音色列表。
`format`	String	否	音频编码格式。取值：`pcm`、`wav`、`mp3`、`opus`，默认`pcm`。使用SDK时，选择对应的`OutputFormatEnum`枚举值。
`sample_rate`	Integer	否	音频采样率，单位Hz。取值：`8000`、`16000`、`24000`、`48000`，默认`16000`。选择音色支持的采样率。SDK中的对应枚举为`SAMPLE_RATE_8K`、`SAMPLE_RATE_16K`、`SAMPLE_RATE_24K`、`SAMPLE_RATE_48K`。
`volume`	Integer	否	音量，范围为0～100，默认50。
`speech_rate`	Integer	否	语速，范围为-500～500，默认0。
`pitch_rate`	Integer	否	语调，范围为-500～500，默认0。
`bit_rate`	Integer	否	音频码率，仅对OPUS生效。范围为6～510 kbit/s，默认32。
`enable_subtitle`	Boolean	否	设为`true`开启字级时间戳，需选择支持时间戳的音色。
`enable_ssml`	Boolean	否	设为`true`开启SSML，需选择支持SSML的音色。开启后，每个会话仅发送一次完整的SSML文本。
`enable_aigc_tag`	Boolean	否	是否在生成的音频中添加AIGC隐性标识，默认`false`。设为`true`时，将标识嵌入WAV、MP3或OPUS音频中。
`aigc_propagator`	String	否	AIGC隐性标识中的`ContentPropagator`字段，用于标识内容传播者，默认为阿里云UID。仅在`enable_aigc_tag`为`true`时生效。
`aigc_propagate_id`	String	否	AIGC隐性标识中的`PropagateID`字段，用于唯一标识一次传播行为，默认为本次合成请求的Task ID。仅在`enable_aigc_tag`为`true`时生效。

待合成文本

通过RunSynthesis消息发送文本，其payload包含以下参数。

参数	类型	是否必选	说明
`text`	String	是	待合成文本，采用UTF-8编码。长度限制请参见功能与使用限制。

响应事件

服务端通过WebSocket返回JSON事件和语音二进制数据。JSON事件的header.name表示事件名称，header.status表示业务状态，header.status_text包含状态信息。

事件类型

事件	说明
`SynthesisStarted`	任务已开始，可以发送文本。
`SentenceBegin`	当前句子开始，`payload.index`为句子索引。
`SentenceSynthesis`	当前句子的合成事件。开启字级时间戳时，`payload.subtitles`包含字幕和时间戳信息。
`SentenceEnd`	当前句子合成结束。开启字级时间戳时，返回该句的字幕和时间戳信息。
`SynthesisCompleted`	当前任务合成完成，`payload`包含字符计量信息。
`TaskFailed`	任务失败，错误状态和描述位于`header.status`及`header.status_text`中。

字级时间戳

使用支持时间戳的音色，并将enable_subtitle设为true。SentenceSynthesis和SentenceEnd事件的payload.subtitles为字幕数组，主要字段如下。

字段	类型	说明
`text`	String	字幕文本。
`begin_index`	Integer	字幕文本的起始索引。
`end_index`	Integer	字幕文本的结束索引。
`begin_time`	Integer	字幕对应音频的开始时间，单位毫秒。
`end_time`	Integer	字幕对应音频的结束时间，单位毫秒。

合成完成与计量

SynthesisCompleted事件中的payload.measureLength表示本次合成的字符计量。1个汉字计为2个字符；1个英文字母、标点或句子中间的空格计为1个字符。

完成事件示例如下。

{
    "header": {
        "message_id": "05450bf69c53413f8d88aed1ee60****",
        "task_id": "640bc797bb684bd6960185651307****",
        "namespace": "FlowingSpeechSynthesizer",
        "name": "SynthesisCompleted",
        "status": 20000000,
        "status_text": "Gateway:SUCCESS:Success."
    },
    "payload": {
        "measureType": "TextLengthHD",
        "measureAmount": 1,
        "measureLength": 5
    }
}

音色列表

在voice参数中指定音色名称。各音色支持的语种、采样率、时间戳和SSML能力请参见以下列表。

使用NLS复刻音色时，将声音复刻服务返回的VoiceName作为voice参数值。创建和使用方法请参见CosyVoice声音复刻说明与SDK示例。

错误码

根据TaskFailed事件中的错误状态和描述排查问题，具体错误码及处理方法请参见错误码查询。