API详情

流式文本语音合成

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

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

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

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

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

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

前提条件

• 获取鉴权需要的Appkey以及Token。具体操作，请参见管理项目和通过SDK获取Token。

• 如果通过SDK方式接入，需要下载安装SDK。具体操作，请参见快速开始。

服务地址

服务交互流程说明

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

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

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

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

API接口说明

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

  Android-Java

  /**
   * 初始化并建连，开始流式语音合成任务
   * @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);

  Object C

  /**
   * 与服务端完成建链，并开始流式语音合成任务
   * @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;

  Java

  /**
   * 开始语音转写：发送语音转写请求，同步接收服务端确认
   * @throws Exception
   */
  public void startSteamInputTTS()

  Python

  """
  开始语音转写：发送语音转写请求，同步接收服务端确认
  
  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：以流式的方式发送文本

  Android-Java

  /**
   * 以流式的方式发送文本
   * @param text：从大模型当中生成的流式文本
   * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
   */
  public synchronized int sendStreamInputTts(String text);

  Object C

  /**
   * 以流式的方式发送文本
   * @param text：从大模型当中生成的流式文本
   * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
   */
  - (int) sendStreamInputTts:(const char *)text;

  Java

  /**
   * 以流式的方式发送文本
   * @throws Exception
   * @param text：从大模型当中生成的流式文本
   */
  public void sendStreamInputTts(String text);

  Python

  """
  以流式的方式发送文本
  Parameters:
  -----------
  text: str
      utf-8 text
  """
  def sendStreamInputTts(self, text)

• stopStreamInputTts：以阻塞的方式停止流式文本语音合成，并与服务端断开websocket连接

  Android-Java

  /**
   * 结束合成任务，通知服务端流入文本数据发送完毕，阻塞等待服务端处理完成，并返回所有合成音频。阻塞超时可以通过start接口中的complete_waiting_ms设置
   * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
   */
  public synchronized int stopStreamInputTts()

  Object C

  /**
   * 停止合成任务，等待收到剩余合成结果后返回
   * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
   */
  public synchronized int stopStreamInputTts()

  Java

  /**
   * 结束合成任务，通知服务端流入文本数据发送完毕，阻塞等待服务端处理完成，并返回所有合成音频。阻塞超时可以通过start接口中的complete_waiting_ms设置
   */
  public void stopStreamInputTts()

  Python

  """
  停止合成任务，等待收到剩余合成结果后返回
  """
  def stopStreamInputTts(self)

• 回调函数说明

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

  Android-Java

  /**
   * 事件回调
   * @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);

  Object C

  /**
   * 事件回调
   * @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;

  Java

  /**
   * 服务端检测到了一句话的开始
   * @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);

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

  Android-Java

  /**
   * 语音合成流式数据返回
   * @param data：合成的音频数据，写入播放器。
   */
  void onStreamInputTtsDataCallback(byte[] data);

  Object C

  /**
   * 当开始识别时，此回调被连续调用，App需要在回调中进行语音数据填充，语音数据来自App的录音
   * @param data: 合成的语音数据，写入播放器
   * @param len: 合成的语音长度
   */
  - (void)onStreamInputTtsDataCallback:(char*)data len:(int)len;

  Java

  /**
  * 接收到语音合成音频数据流
  * @param message 二进制音频数据
  */
  abstract public void onAudioData(ByteBuffer message);

移动端SDK回调事件说明

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

常见SDK错误码

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