CosyVoice TTS

基础信息

项目	说明
Base URL
输入音频	wav / mp3 / m4a / flac / ogg
输出（非流式）	JSON，audio_base64 字段为 WAV base64
输出（流式）	直接返回 WAV 音频流（audio/wav）
采样率	24000 Hz
模型	Fun-CosyVoice3-0.5B-2512
语言	中/英/日/韩/德/西/法/意/俄 + 18种方言

接口一览

接口	方法	返回	用途
`/health`	GET	JSON	健康检查
`/tts`	POST	JSON	纯文字合成
`/tts/stream`	POST	WAV流	流式纯文字合成
`/tts/set_default_voice`	POST	JSON	设置默认声音
`/tts/clone`	POST	JSON	声音克隆
`/tts/stream/clone`	POST	WAV流	流式声音克隆
`/tts/instruct`	POST	JSON	情感控制
`/tts/stream/instruct`	POST	WAV流	流式情感控制

非流式接口参数

POST /tts

参数	类型	必填	默认	说明
text	string	是	-	要合成的文字
speed	float	否	1.0	语速 0.5~2.0
seed	int	否	-1	随机种子

POST /tts/clone

参数	类型	必填	默认	说明
text	string	是	-	要合成的文字
audio	file	是	-	参考音频
speed	float	否	1.0	语速
seed	int	否	-1	随机种子

POST /tts/instruct

参数	类型	必填	默认	说明
text	string	是	-	要合成的文字
instruct	string	是	-	风格指令
audio	file	是	-	参考音频
speed	float	否	1.0	语速
seed	int	否	-1	随机种子

流式接口

流式接口参数与非流式完全相同，区别是直接返回 WAV 音频流而不是 JSON。浏览器可以边下载边播放。

非流式	对应流式
`/tts`	`/tts/stream`
`/tts/clone`	`/tts/stream/clone`
`/tts/instruct`	`/tts/stream/instruct`

instruct 指令示例

指令	效果
`用开心的语气说`	开心
`用愤怒的语气说`	愤怒
`用温柔的语气说`	温柔
`用悲伤的语气说`	悲伤
`请用广东话表达`	粤语
`请用四川话表达`	四川话
`轻声说`	降低音量

调用示例

Python（非流式）

import requests, base64

resp = requests.post(
    "http://服务器:8001/tts",
    data={"text": "你好，DDR5内存价格299美元"},
    timeout=120
)
audio = base64.b64decode(resp.json()["audio_base64"])
with open("output.wav", "wb") as f:
    f.write(audio)

Python（流式，边生成边保存）

import requests

resp = requests.post(
    "http://服务器:8001/tts/stream",
    data={"text": "你好，这是流式合成测试"},
    stream=True, timeout=120
)
with open("stream.wav", "wb") as f:
    for chunk in resp.iter_content(chunk_size=4096):
        f.write(chunk)
        # 实时场景可以在这里边写边播

curl（非流式）

curl -X POST http://服务器:8001/tts \
  -F "text=你好世界" -F "speed=1.0"

curl（流式，直接保存 WAV）

curl -X POST http://服务器:8001/tts/stream \
  -F "text=你好世界" -o output.wav

JavaScript（流式播放）

const fd = new FormData();
fd.append('text', '你好世界');

const resp = await fetch('/tts/stream', {method:'POST', body:fd});
const blob = await resp.blob();
const url = URL.createObjectURL(blob);
const audio = new Audio(url);
audio.play();

AI 助理快速集成

import requests, base64

def speak(text, speed=1.0):
    resp = requests.post(
        "http://服务器:8001/tts",
        data={"text": text, "speed": speed},
        timeout=120
    )
    resp.raise_for_status()
    return base64.b64decode(resp.json()["audio_base64"])

def speak_stream(text, output_path, speed=1.0):
    resp = requests.post(
        "http://服务器:8001/tts/stream",
        data={"text": text, "speed": speed},
        stream=True, timeout=120
    )
    with open(output_path, "wb") as f:
        for chunk in resp.iter_content(4096):
            f.write(chunk)

性能参考（1080 Ti）

文字长度	非流式	流式首包
10字	5-8秒	3-5秒
30字	10-15秒	3-5秒
100字	30-45秒	3-5秒

流式模式下首包延迟固定约 3-5 秒，之后边生成边传输，用户感知延迟大幅降低。

注意事项

项目	说明
超时	建议 120 秒
并发	1（多请求排队）
单次长度	建议不超过 200 字
参考音频	3-10秒清晰单人语音
自动预处理	符号、emoji 自动清理

Swagger 交互文档：/docs