实时超自然语音合成-普通话版(算法编码：8000200010)

接口信息

API Path
/aipaas/voice/v1/tts/supernaturalrt

请求协议
WS

建立连接时的请求参数（websocket open） ：

请求头部 ：

头部标签	必填	说明	类型	数据字典	限制	头部内容	示例
Content-Type	是	application/json	[string]			application/json	application/json
X-APP-ID	是	控制台--应用管理--AppID	[string]
Device-Uuid	否	设备管理-设备uuid	[string]
Authorization	是	鉴权信息	[string]

Query参数 ：

参数名	说明	必填	类型	限制	示例
app_id	由客户端传入，便于排查问题	否	[string]
建立连接时的响应内容（websocket open） ：
请求报文 ：

请求参数 Json
Object

参数名	说明	必填	类型	数据字典	限制	示例
req_id	请求全局唯一 ID，记录该值便于排查问题	是	[string]
text	待合成的文本，需要为 UTF-8 编码	是	[string]
format	音频编码格式，支持 PCM 格式，默认值：PCM	否	[string]
sample_ rate	音频采样率，支持 24000Hz、22050Hz、16000 Hz 和 8000 Hz，默认值：24000	否	[int]
voice	说话人，支持音色 cixingnan、songchinan、surennan、 cixingnan2、zhubonan、kefunan、zhuchinan、jilunan2、 surennv、xianliaonv、mansunv、kefunv1、huoponv、 ruyanv、xinwennv、kefunv2、luolinv、huoponv2、 qingtiannv、cixingnan3、gaojinv、gushinan2、jilunan1、 kejinan1、kejinan2、pingdannv、tuokouxiu、xuanyinan、 sarah， 默认音色为 cixingnan	否	[string]
speech_rate	语速，取值范围：[0.5, 2.0]，默认值：1.0	否	[float]
volume	音量，取值范围：[0, 100]，默认值：50	否	[int]
响应报文 ：

返回结果

> 成功 (200)
> Json
> Object

参数名	说明	必填	类型	数据字典	限制	示例
status	状态码，与code相同（注：2025年11⽉30⽇后不再返回此字段）	是	[int]
status_msg	状态说明，与message相同（注：2025年11⽉30⽇后不再返回此字段）	是	[string]
code	状态码，⻅服务码说明	是	[int]
message	状态说明，⻅服务码说明	是	[string]
sid	会话全局唯一 id，用于记录本次会话	否	[string]
result	合成结果	否	[object]
result>>audio	合成音频数据，经过 base64 编码	否	[string]
result>>audio_len	合成音频长度，单位：ms	否	[int]
result>>is_end	标志位。true：最后一个合成片段；false：中间合成片段	否	[boolean]

详细说明 ：

1. 功能简介

超自然流式语音合成提供将输入文本合成为语音二进制数据的功能。

• 支持普通话；
• 支持输出格式：PCM 编码；
• 支持设置采样率：8000 Hz，16000 Hz， 22050Hz，24000Hz；
• 音频为单声道，位深为 16 bit；
• 支持设置音量；
• 支持设置多种说话人；
• 支持一次性合成 500 字符以内的文字，其中 1 个汉字、1 个英文字母、1 个标点或 1 个句子中间空格均算作 1 个字符，超过 500 个字符的内容将会截断，超过500字的文字不再进行合成；
• 仅支持采用 UTF-8 编码的文本输入。
• 在接⼝文档中，非必填字段的处理应遵循以下原则，根据具体场景灵活选择：
  1. 不需要时直接忽略（推荐） 原则：除非有明确业务需求，否则不要传递非必填字段。 原因：减少请求数据冗余。避免传递不合理值导致接⼝报错。
  2. 需要时传递有效值 场景：当业务确实需要该字段的功能时，按文档要求传递有效值。 注意事项：确保值符合类型和格式要求（如字符串、数字、特定格式等）。 空值需明确约定（⻅第3点）。
  3. 空值传递规范 关键点：切勿⽤ null 或 "" 等隐式空值，除非文档明确允许。 正确做法： 查阅文档：看是否定义了空值处理⽅式。 约定缺省⾏为：如⽆说明，建议不同空值处理⽅式： 数值类型：不传字段（传 0 可能被误认为有效值）。 字符串类型：不传字段。若必须传空，先确认接⼝是否⽀持 ""。 布尔类型：不传字段（避免误解 false 为有意赋值）。
  4. 默认值处理 原则：服务端通常会为非必填字段设置默认值。 操作： 忽略字段：直接接受默认值（如⾳量参数 volume 默认为 50）。 覆盖默认值：有特殊需求时主动传递新值。

2. 修订历史

日期	版本	修订内容
2025-11-04	v3.2.0	修改功能介绍；修改状态码；入参新增speech_rate字段；出参注明status和status_msg下线时间
2025-08-11	v3.0	修改部分字段说明
2025-03-18	v1.6.5.8	初始化API文档

3. 服务鉴权

服务接口调用时需要严格遵循服务鉴权规则，服务调用鉴权规则请参见：开发指南 - 接口签名认证。

4. 状态码说明

握手返回结果

WS CODE	说明	错误描述信息	解决方法
101	成功	{"message":"success"}	成功，开始语音合成
4001	签名校验失败，授权失败	{"message":"check sign fail"}	联系商务，更新授权
4002	并发请求过多	{"message":"Too many requests."}	联系商务，增加并发

返回码	解释	说明	解决方法
10301	Parameter error	参数错误	检查请求体是否符合接口协议
10304	Parse request body fail	请求格式错误	查看请求的 URL body 格式是否正确，参考接口文档
10503	Server connection time out	服务连接超时	联系技术人员
10903	Synthesis failed	合成失败	联系技术人员
10000	Success	成功	执行下一步操作

通用状态码请参考【状态码】中的【网关认证】

5. 请求出入参示例

5.1 调用示例
客户端发起请求，服务端确认请求有效。其中在请求消息中进行参数设置

{
   "req_id": "3a87fe9793c9-4ebd-95d4-4ce2-a80c054b",
   "text": "今天是周⼀，天⽓挺好的。"
}

5.2 开始合成响应示例
客户端发起开始检测请求后，服务端建立连接，并进行签名校验以及参数解析，校验成功并且解析成功，则返回对应的消息表示握手成功；如果校验失败或解析失败，服务端返回对应的消息并断开连接。

{ 
    "code": 10000,
    "message": "Success",
    "status": 10000,
    "status_msg": "Success",
    "sid": "4eHgiLCBhbGdvcml" 
}

5.3 接收合成数据响应示例
服务端返回合成的语音二进制数据。客户端接收到服务端发送的确认合成请求有效的响应后，开始循环接收语音数据。

{
    "code": 10000,
    "message": "Success",
    "status": 10000,
    "status_msg": "Success",
    "result": {
        "audio": "//6YYmNiDlSUXjZlDP8yADQAQ1E2ANKJOaTqFGUgIwDQAKAA==",
        "audio_len": 2500,
        "is_end": false
    }
}

5.4 合成结束响应示例
语音合成完毕，服务端发送合成完毕事件通知

{
    "code": 10000,
    "message": "Success",
    "status": 10000,
    "status_msg": "Success",
    "result": {
        "audio": "//6YYmNiDlSUXjZlDP8yADQAQ1E2ANKJOaTqFGUgIwDQAKAA==",
        "audio_len": 2500,
        "is_end": true
    }
}

6. 调用示例

6.1 Java版本

import com.alibaba.fastjson.JSONObject;
import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.HashMap;
import java.util.Map;

/**
 * 为保证示例可以正常运行，请确认maven中是否存在以下依赖：
 * 
 *     org.java-websocket
 *     Java-WebSocket
 *     1.5.3
 * 
 * 
 *     com.alibaba
 *     fastjson
 *     2.0.49
 * 
 */
public class WebSocketExample extends WebSocketClient {

    public WebSocketExample(URI serverUri, Map headers) {
        super(serverUri, headers);
    }

    public static void main(String[] args) {
        try {
            // 创建WebSocket客户端
            URI uri = new URI("算法调用地址");
            Map headers = new HashMap();
            //调用鉴权
            headers.put("X-APP-ID", "yourAppId");
            headers.put("Authorization", "yourAuthorization");

            WebSocketExample client = new WebSocketExample(uri, headers);
            client.connect();

            // 等待一段时间后关闭连接
            Thread.sleep(5000);
            client.close();
        } catch (URISyntaxException | InterruptedException e) {
            e.printStackTrace();
            System.out.println("WebSocket error: " + e.getMessage());
        }
    }

    @Override
    public void onOpen(ServerHandshake handshakedata) {
        System.out.println("WebSocket connection opened");
        // 发送消息
        try {
            // 初始化连接消息
            JSONObject initSend = new JSONObject();
            initSend.put("req_id", "test001");
            initSend.put("text", "yourText");
            send(initSend.toJSONString());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    @Override
    public void onMessage(String message) {
        System.out.println("Received message: " + message);
    }

    @Override
    public void onClose(int code, String reason, boolean remote) {
        System.out.println("WebSocket connection closed: " + reason);
    }

    @Override
    public void onError(Exception ex) {
        System.err.println("WebSocket error: " + ex.getMessage());
    }

}

6.2 Python版本

import argparse
import asyncio
import websockets
import json
import base64
import logging
import time

# 配置日志，设置日志级别为INFO，并指定日志格式
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger()

async def uws_call(args):
    # 获取命令行参数中的URL
    url = args.url
    # 记录开始时间
    start_time = time.time()
    logger.info(f"开始建立websocket连接，获取当前时间：{start_time}")
  
    header = {
        "Content-Type": "application/json",
        'X-APP-ID': args.X_APP_ID,
        'Authorization': args.Authorization
    }
  
    # 建立WebSocket连接
    async with websockets.connect(url, extra_headers=header) as websocket:
        logger.info("=================================请求参数start_json===============================")
        # 构建请求参数
        start_json = {
            'req_id': 'test001',
            'text': 'yourText'
        }
        logger.info(f"请求参数：{start_json}")
        # 发送请求参数
        await websocket.send(json.dumps(start_json))
      
        try:
            # 接收响应
            resp_str = await websocket.recv()
            resp_data = json.loads(resp_str)

            if resp_data['status'] == 10000:
                logger.info('Received initial response: %s', resp_str)
                # 记录连接建立（即收到第一个响应）的时间
                connection_established_time = time.time()
                logger.info('WebSocket connection established in %.2f seconds',
                            connection_established_time - start_time)
                is_end = False
                # 打开文件以写入音频数据
                with open("test.pcm", "wb") as f:
                    while not is_end:
                        # 接收音频数据
                        resp_audio_str = await websocket.recv()
                        resp_audio_data = json.loads(resp_audio_str)

                        if resp_audio_data['status'] != 10000:
                            logger.error('Received non-success status: %s', resp_audio_data)
                            break

                        if 'result' in resp_audio_data:
                            synth_info = resp_audio_data['result']
                            logger.info('Received synthesis info: %s', synth_info)
                            # 解码音频数据并写入文件
                            audio_wav = base64.b64decode(synth_info['audio'])
                            f.write(audio_wav)
                            is_end = synth_info['is_end']
                        else:
                            logger.error('No result in response: %s', resp_audio_data)
                            break
                # 计算整个交互的耗时（从尝试连接到接收完所有消息）
                total_duration = time.time() - start_time
                logger.info('Total interaction duration: %.2f seconds', total_duration)

        except websockets.exceptions.ConnectionClosed as e:
            logger.error('WebSocket connection closed: %s', e)
            # 如果连接关闭了，我们仍然可以记录到目前为止的耗时
            logger.info('Duration until connection closed: %.2f seconds', time.time() - start_time)
        except Exception as e:
            logger.error('An error occurred: %s', e)
            # 如果发生错误，我们同样记录到目前为止的耗时
            logger.info('Duration until error occurred: %.2f seconds', time.time() - start_time)
        finally:
            # 关闭WebSocket连接
            await websocket.close()

def main(args):
    # 运行异步函数
    asyncio.get_event_loop().run_until_complete(uws_call(args))

if __name__ == '__main__':
    # 解析命令行参数
    parser = argparse.ArgumentParser()
    parser.add_argument('--url', type=str, default='算法调用地址')
    parser.add_argument('--X_APP_ID', type=str, default='yourAppId')
    parser.add_argument('--Device_Uuid', type=str, default='yourDeviceUuid')
    parser.add_argument('--Authorization', type=str, default='yourAuthorization')
    args = parser.parse_args()
  
    # 调用主函数
    main(args)