文档

API详情

更新时间:

流式文本语音合成

流式文本语音合成可以将流式文本合成为语音二进制数据,并实时地、流式地返回结果。终端用户可以听到接近同步的语音输出,从而极大地提升交互体验,减少了等待时间。一个典型适用的场景是,将大规模语言模型(LLM)返回的流式文本,无需做任何处理(如拼接、整合等),直接送入流式文本语音合成服务,并得到实时音频流。流式文本语音合成还具备如下特点:

  • 支持输出PCM、WAV和MP3编码格式的数据。

  • 支持流式发送文本。在同一会话中,可以分批次发送文本并接收音频。所合成的音频能够实时播放,且具有低延迟的特点。此外,每次发送的文本不需要构成完整的单词或句子,服务端将根据语义进行恰当的断句和重组。

  • 在同一个流式TTS会话中,单次合成不超过2万字符,总计不超过20万字符,其中1个汉字算作2个字符,1个英文字母、1个标点或1个句子中间空格均算作1个字符。

  • 支持采用UTF-8编码的文本输入。

  • 支持设置不同场景的声音。

前提条件

服务地址

访问类型

说明

URL

外网访问(默认北京地域)

所有服务器均可使用外网访问URL(SDK中默认设置了外网访问URL)。

北京:wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1

ECS内网访问

使用阿里云北京ECS(即ECS地域为华北2(北京)),可使用内网访问URL。 ECS的经典网络不能访问AnyTunnel,即不能在内网访问语音服务;如果希望使用AnyTunnel,需要创建专有网络在其内部访问。

说明

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

关于ECS的网络类型请参见网络类型

北京:ws://nls-gateway-cn-beijing-internal.aliyuncs.com:80/ws/v1

服务交互流程说明

客户端与服务端的交互流程分为三个阶段:

  • 阶段一:客户端会与服务端建立连接,并发送【StartSynthesis】指令,服务端返回响应的事件以确认建立连接成功,并可以正式开启TTS语音合成服务。

  • 阶段二:用户循环调用发送文本接口,向服务端发送文本流。同时服务端返回语音合成数据以及相应的事件响应。

  • 阶段三:文本发送完毕后,客户端调用【StopSynthesis】指令,此时客户端会等待服务端将所有的语音合成数据发送完毕后断开连接。

image

API接口说明

说明

本文仅提供SDK API说明,此外您还可以通过WebSocket协议方式接入,详情参考WebSocket协议说明

  • startStreamInputTts:与服务端进行websocket建连操作,并完成回调、参数设置等操作

    /**
     * 初始化并建连,开始流式语音合成任务
     * @param callback:事件监听回调,参见下文具体回调。
     * @param ticket:json string形式的鉴权参数,参见下方参数设置
     * @param parameters:json string形式的初始化配置参数,参见下方说明或接口说明:xxxxx
     * @param session_id:会话ID,可传入32个字节的uuid,或传入空内容由SDK自动生成。
     * @return:参见错误码:https://help.aliyun.com/document_detail/459864.html。
     */
    public synchronized int startStreamInputTts(INativeTtsCallback callback,
                                                String ticket,
                                                String parameters
                                                String session_id);
    /**
     * 与服务端完成建链,并开始流式语音合成任务
     * @param ticket:json string形式的鉴权参数,参见下方说明或接口说明:xxxxx
     * @param parameters:json string形式的初始化配置参数,参见下方说明或接口说明:xxxxx
     * @param session_id:会话ID,可传入32个字节的uuid,或传入空内容由SDK自动生成。
     * @param level:log打印级别,值越小打印越多。
     * @param save_log:是否保存log为文件,存储目录为ticket中的debug_path字段值。
     * @return:参见错误码:https://help.aliyun.com/document_detail/459864.html。
     */
    - (int) startStreamInputTts:(const char *)ticket 
                                parameters:(const char *)parameters 
                                sessionId:(const char *)sessionId 
                                logLevel:(int)logLevel 
    、                           saveLog:(BOOL)saveLog;
    /**
     * 开始语音转写:发送语音转写请求,同步接收服务端确认
     * @throws Exception
     */
    public void startSteamInputTTS()
    """
    开始语音转写:发送语音转写请求,同步接收服务端确认
    
    Parameters:
    -----------
    voice: str
        voice for text-to-speech, default is xiaoyun
    aformat: str
        audio binary format, support: 'pcm', 'wav', 'mp3', default is 'pcm'
    sample_rate: int
        audio sample rate, default is 24000, support:8000, 11025, 16000, 22050,
        24000, 32000, 44100, 48000
    volume: int
        audio volume, from 0~100, default is 50
    speech_rate: int
        speech rate from -500~500, default is 0
    pitch_rate: int
        pitch for voice from -500~500, default is 0
    ex: dict
        dict which will merge into 'payload' field in request
    """
    def startStreamInputTts(
        self,
        voice="longxiaochun",
        aformat="pcm",
        sample_rate=24000,
        volume=50,
        speech_rate=0,
        pitch_rate=0,
    )

    parameter参数设置说明

    参数

    类型

    是否必选

    说明

    appkey

    String

    管控台创建的项目Appkey。

    token

    String

    如果需要更新,则进行设置。

    voice

    String

    发音人,默认是longxiaochun。

    format/aformat(python sdk)

    String

    音频编码格式,默认值:pcm。支持格式:pcm、wav、mp3。

    sample_rate

    String

    音频采样率,默认值:24000

    volume

    String

    朗读音量,范围是0~100,默认50。

    speech_rate

    String

    语速,范围是-500~500,默认是0。

    pitch_rate

    String

    语调,取值范围:-500~500,默认值:0,值越大声音越尖锐。

  • sendStreamInputTts:以流式的方式发送文本

    /**
     * 以流式的方式发送文本
     * @param text:从大模型当中生成的流式文本
     * @return:参见错误码:https://help.aliyun.com/document_detail/459864.html。
     */
    public synchronized int sendStreamInputTts(String text);
    /**
     * 以流式的方式发送文本
     * @param text:从大模型当中生成的流式文本
     * @return:参见错误码:https://help.aliyun.com/document_detail/459864.html。
     */
    - (int) sendStreamInputTts:(const char *)text;
    /**
     * 以流式的方式发送文本
     * @throws Exception
     * @param text:从大模型当中生成的流式文本
     */
    public void sendStreamInputTts(String text);
    """
    以流式的方式发送文本
    Parameters:
    -----------
    text: str
        utf-8 text
    """
    def sendStreamInputTts(self, text)
  • stopStreamInputTts:以阻塞的方式停止流式文本语音合成,并与服务端断开websocket连接

    /**
     * 结束合成任务,通知服务端流入文本数据发送完毕,阻塞等待服务端处理完成,并返回所有合成音频。阻塞超时可以通过start接口中的complete_waiting_ms设置
     * @return:参见错误码:https://help.aliyun.com/document_detail/459864.html。
     */
    public synchronized int stopStreamInputTts()
    /**
     * 停止合成任务,等待收到剩余合成结果后返回
     * @return:参见错误码:https://help.aliyun.com/document_detail/459864.html。
     */
    public synchronized int stopStreamInputTts()
    /**
     * 结束合成任务,通知服务端流入文本数据发送完毕,阻塞等待服务端处理完成,并返回所有合成音频。阻塞超时可以通过start接口中的complete_waiting_ms设置
     */
    public void stopStreamInputTts()
    """
    停止合成任务,等待收到剩余合成结果后返回
    """
    def stopStreamInputTts(self)
  • 回调函数说明

    事件回调函数:用于响应回调事件

    /**
     * 事件回调
     * @param event:回调事件,参见如下事件列表。
     * @param task_id:请求的任务ID,每次调用一个新ID。
     * @param session_id:请求的会话ID。
     * @param ret_code:参见错误码,出现TTS_EVENT_ERROR事件时有效,可查阅https://help.aliyun.com/document_detail/459864.html。。
     * @param error_msg:当产生错误码时,返回错误信息。
     * @param timestamp:时间戳信息。
     * @param all_response:返回的完整json格式信息。
     */
    void onStreamInputTtsEventCallback(StreamInputTtsEvent event,
                                       String task_id, String session_id, 
                                       int ret_code, String error_msg,
                                       String timestamp, String all_response);
    /**
     * 事件回调
     * @param event:回调事件,参见如下事件列表。
     * @param task_id:请求的任务ID,每次调用一个新ID。
     * @param session_id:请求的会话ID。
     * @param ret_code:参见错误码,出现TTS_EVENT_ERROR事件时有效,
     *   可查阅https://help.aliyun.com/document_detail/459864.html。。
     * @param error_msg:当产生错误码时,返回错误信息。
     * @param timestamp:时间戳信息。
     * @param all_response:返回的完整json格式信息。
     */
    - (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;
    /**
     * 服务端检测到了一句话的开始
     * @param response
     */
    abstract public void onSentenceBegin(
        StreamInputSpeechSynthesizerResponse response);
    
    /**
     * 服务端检测到了一句话的结束,并返回这句话的起止位置与所有时间戳
     * @param response
     */
    abstract public void onSentenceEnd(
        StreamInputSpeechSynthesizerResponse response);
    /**
     * 合成结束
     * @param response
     */
    abstract public void onSynthesisComplete(
        StreamInputSpeechSynthesizerResponse response);
    /**
     * 失败处理
     * @param response
     */
    abstract public void onFail(StreamInputSpeechSynthesizerResponse response);
    /**
     * 增量在response=>payload中返回时间戳
     * @param response
     */
    abstract public void onSentenceSynthesis(
        StreamInputSpeechSynthesizerResponse response);

    数据回调函数:用于语音合成数据返回

    /**
     * 语音合成流式数据返回
     * @param data:合成的音频数据,写入播放器。
     */
    void onStreamInputTtsDataCallback(byte[] data);
    /**
     * 当开始识别时,此回调被连续调用,App需要在回调中进行语音数据填充,语音数据来自App的录音
     * @param data: 合成的语音数据,写入播放器
     * @param len: 合成的语音长度
     */
    - (void)onStreamInputTtsDataCallback:(char*)data len:(int)len;
    /**
    * 接收到语音合成音频数据流
    * @param message 二进制音频数据
    */
    abstract public void onAudioData(ByteBuffer message);

移动端SDK回调事件说明

名称

说明

TTS_EVENT_SYNTHESIS_STARTED

建连成功,语音合成准备开始,准备播放。对应startStreamInputTts。

TTS_EVENT_SENTENCE_BEGIN

服务端检测到了一句话的开始。

TTS_EVENT_SENTENCE_SYNTHESIS

有新的合成结果返回。

TTS_EVENT_SENTENCE_END

服务端检测到了一句话的结束,返回该句的全量时间戳。

TTS_EVENT_SYNTHESIS_COMPLETE

语音合成结束,合成数据已全部下发。本轮交互终止。

TTS_EVENT_TASK_FAILED

语音合成发生错误

Python回调函数在创建对象时作为参数配置,说明见下表:

参数

参数说明

on_data

当存在合成数据后的回调参数。回调参数包含以下两个:

  • 对应start方法中aformat的二进制音频数据

  • 用户自定义参数

其中,用户自定义参数为下方callback_args字段中返回的参数内容。

on_sentence_begin

收到SentenceBegin事件时回调。回调参数包含以下两个

  • JSON形式的字符串

  • 用户自定义参数

其中,用户自定义参数为下方callback_args字段中返回的参数内容。

on_sentence_synthesis

收到SentenceSynthesis事件时回调。回调参数包含以下两个

  • JSON形式的字符串

  • 用户自定义参数

其中,用户自定义参数为下方callback_args字段中返回的参数内容。

on_sentence_end

收到SentenceEnd事件时回调。回调参数包含以下两个

  • JSON形式的字符串,包含这句话的起止位置与所有时间戳

  • 用户自定义参数

其中,用户自定义参数为下方callback_args字段中返回的参数内容。

on_complete

收到SynthesisCompleted事件时回调。回调参数包含以下两个

  • JSON形式的字符串

  • 用户自定义参数

其中,用户自定义参数为下方callback_args字段中返回的参数内容。

on_error

当SDK或云端出现错误时的回调参数。回调参数包含以下两个:

  • JSON形式的字符串

  • 用户自定义参数

其中,用户自定义参数为下方callback_args字段中返回的参数内容。

on_close

当和云端连接断开时的回调参数。回调参数为用户自定义参数,即用户自定义参数为下方callback_args字段中返回的参数内容。

常见SDK错误码

更多错误码详情参见错误码查询

状态码

状态消息

原因

解决方案

144500

TTS_STREAM_INPUT_INTERNAL_WRONG_STATE

内部状态错误,调用内部指令和状态不匹配

请检查是否存在下述错误:

  1. 外部调用顺序错误

  2. 收到Failed之后继续调用接口。

144501

TTS_STREAM_INPUT_SEND_REQUEST_FAIL

发送websockt数据失败

请检查Websocket连接是否正常。

144502

TTS_STREAM_INPUT_START_TIMEOUT

流式TTS调用start后10秒未收到started指令超时

请检查是否存在下述错误:

  1. start发送失败,请重试。

  2. 请检查连接配置(appkey,url,token)是否正确。

144503

TTS_STREAM_INPUT_STOP_TIMEOUT

流式TTS调用stop后等待complete指令超时

TTS服务卡死或连接中断,联系技术人员排查。

144504

TTS_STREAM_INPUT_INITIALIZED_JSON_INVALID

C++ SDK初始化参数解析失败

请检查输入字符串JSON格式。

144505

TTS_STREAM_INPUT_NOT_CONNECTED

流式TTS未成功建连就调用其他API接口

请在调用connect接口并成功建连后再调用其他接口。

144506

TTS_STREAM_INPUT_MISS_VOICE

没有设定说话人

说话人为必需配置参数。

144507

TTS_STREAM_INPUT_REQUEST_IS_NULL

request为空,初始化失败

请重新尝试用connect建联。