语音合成（同步）

本接口支持基于文本到语音的同步生成，单次可处理最长 500 字符的文本。

支持系统音色自主选择
支持语调、语速、音量、输出格式调整
支持流式输出。

支持音色

表格中为云知声Maas平台系统音色，为您提供语音合成选择。

序号	音色名称 (Voice Name)	音色 ID (Voice ID)	语种	支持方言
1	晨宇	`cn_male_chenyu`	中文、菲律宾语	粤语、四川话、默认
2	晨宇机器人特效	`cn_male_chenyu_robot`	中文	-
3	晨宇苍老	`cn_male_chenyu_elderly`	中文	-
4	晨宇沉稳	`cn_male_chenyu_steady`	中文	-
5	晨宇流利	`cn_male_chenyu_fluent`	中文	-
6	莎莎	`cn_female_shasha`	中文、日语、韩语、泰语、越南语、印尼语、柬埔寨语	-
7	佳佳	`cn_female_jiajia`	中文、印尼语、马来语、缅甸语、老挝语	-
8	若琳	`cn_female_ruolin`	中文	-
9	晓迪温暖	`cn_female_xiaodi_warm`	中文	-
10	Johnny	`en_male_johnny`	英语	-
11	Jane	`en_female_jane`	英语	-

发音情绪

高兴，愤怒，沮丧，低语，大声，中性。目前仅 cn_male_chenyu 发音人，且语种为中文、方言为默认时支持。

使用流程

在 API Key 管理获取密钥，并写入环境变量 API_KEY
建立 WebSocket 连接：wss://maas-api.unisound.com/v1/ws/tts?model=u2-tts（详见同步语音合成 API）。
发送文本帧 start，在其中携带待合成全文 text，并配置 voice_setting / audio_setting
按序接收服务端二进制音频帧（按 audio_setting.format 编码，拼接即为完整音频），并解析文本控制帧
当控制帧 end=true 时，本轮合成结束

过程示例

1. 语音合成

Python

"""
本示例演示同步语音合成。
注意：需要先将密钥写入环境变量 API_KEY；并安装 websockets：pip install websockets
"""
import asyncio
import json
import os

import websockets

API_KEY = os.environ["API_KEY"]
WS_URL = "wss://maas-api.unisound.com/v1/ws/tts?model=u2-tts"

START_FRAME = {
  "type": "start",
  "text": "水泊梁山的故事家喻户晓",
  "voice_setting": {
    "voice_id": "cn_male_chenyu",
    "volume": 50,
    "pitch": 50,
    "bright": 50,
    "language": "zh"
  },
  "pronunciation_dict": {
    "tone": ["水泊梁山/水泊<py>po1</py>梁山"]
  },
  "audio_setting": {
    "audio_sample_rate": 32000,
    "format": "mp3"
  }
}


async def run(output_path: str = "output_audio.mp3"):
  headers = {"Authorization": f"Bearer {API_KEY}"}
  audio_chunks = []

  async with websockets.connect(WS_URL, additional_headers=headers) as ws:
    await ws.send(json.dumps(START_FRAME))
    while True:
      msg = await ws.recv()
      if isinstance(msg, (bytes, bytearray)):
        audio_chunks.append(bytes(msg))
        continue

      frame = json.loads(msg)
      print(frame)
      status_code = frame.get("base_resp", {}).get("status_code", 0)
      if status_code != 0:
        raise RuntimeError(frame.get("base_resp", {}).get("status_msg", "tts failed"))
      if frame.get("end"):
        break

  with open(output_path, "wb") as f:
    for chunk in audio_chunks:
      f.write(chunk)
  print(f"saved: {output_path}, bytes={sum(len(c) for c in audio_chunks)}")


if __name__ == "__main__":
  asyncio.run(run())

2. 解析识别结果

服务端以二进制音频帧流式返回合成结果，并以文本 JSON 控制帧标识本轮结束。当 end=true 时表示本轮合成结束。

Python

# 典型控制帧（合成结束）
{
  "sid": "与 start 中 sid 一致（若客户端传入）",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  },
  "end": true
}

更多字段说明、音频格式与错误码，请参阅同步语音合成 API。也可在模型体验 · 语音合成（同步）中在线调试。