本地部署 CosyVoice 后，主要有三种方式进行 API 调用：原生 Python 代码直接调用（适合集成在自己的 Python 项目中）、搭轻量 FastAPI HTTP 服务（适合跨语言或多服务调用）以及 直接使用 WebUI 自带的 Gradio API。方式一：原生 Python 代码直接调用 (推荐在 Python 环境内使用)如果你需要在自己的 Python 项目里直接引入 CosyVoice，可以直接加载其 CLI 库进行推理。 1. 核心示例代码Pythonimport torchaudio
如果是 CosyVoice 1.0 请 import CosyVoice，2.0 导入 CosyVoice2
from cosyvoice.cli.cosyvoice import CosyVoice2
from cosyvoice.utils.file_utils import load_wav
1. 初始化模型（启动时加载一次即可）
cosyvoice = CosyVoice2('pretrained_models/CosyVoice2-0.5B')
--- 模式 A: Zero-Shot 音色克隆 (最常用) ---
需要：目标文本、参考音频文本、参考音频采样率转换为 16k 的 Tensor
prompt_speech_16k = load_wav('prompt.wav', 16000)
prompt_text = "这是参考音频里面说的原话内容。"
target_text = "你好，这是使用 CosyVoice 本地 API 合成的全新语音。"
运行推理
output = cosyvoice.inference_zero_shot(
tts_text=target_text,
prompt_text=prompt_text,
prompt_speech_16k=prompt_speech_16k,
stream=False, # 是否流式输出
speed=1.0 # 控制语速
)
保存生成的音频
for i, res in enumerate(output):
# res['tts_speech'] 结构为 torch.Tensor
torchaudio.save(f'output_zero_shot_{i}.wav', res['tts_speech'], cosyvoice.sample_rate)
--- 模式 B: 跨语言音色克隆 (Cross-Lingual) ---
用中文参考音频，输出英文/日文/韩文等其他语言
prompt_speech_16k = load_wav('chinese_prompt.wav', 16000)
english_text = "Hello, this is a cross-lingual voice cloning test."
output = cosyvoice.inference_cross_lingual(
tts_text=english_text,
prompt_speech_16k=prompt_speech_16k,
stream=False
)
for i, res in enumerate(output):
torchaudio.save(f'output_cross_{i}.wav', res['tts_speech'], cosyvoice.sample_rate)
方式二：封装 FastAPI 提供 RESTful HTTP API (跨语言/远程调用)如果你的主程序是 Java、Go、Node.js 或前端，需要通过 HTTP 接口访问，可以写一个简单的 FastAPI 服务脚本 api_server.py。1. 创建 api_server.py 脚本在 CosyVoice 项目根目录下新建 api_server.py：Pythonimport io
import torchaudio
from fastapi import FastAPI, Form, File, UploadFile
from fastapi.responses import Response
import uvicorn
from cosyvoice.cli.cosyvoice import CosyVoice2
from cosyvoice.utils.file_utils import load_wav
app = FastAPI(title="CosyVoice Local API")
全局单例加载模型
print("正在加载 CosyVoice 模型...")
cosyvoice = CosyVoice2('pretrained_models/CosyVoice2-0.5B')
print("模型加载完成！")
@app.post("/v1/tts/zero-shot")
async def zero_shot_tts(
text: str = Form(..., description="待合成的中文或外文文本"),
prompt_text: str = Form(..., description="参考音频对应的文字内容"),
prompt_wav: UploadFile = File(..., description="参考音频文件 (.wav / .mp3)")
):
# 读取上传的音频并转换为 16k 采样率的 Tensor
content = await prompt_wav.read()
prompt_speech_16k = load_wav(io.BytesIO(content), 16000)
# 推理合成
output = cosyvoice.inference_zero_shot(
tts_text=text,
prompt_text=prompt_text,
prompt_speech_16k=prompt_speech_16k,
stream=False
)
# 获取音频 Tensor 并保存到内存 Buffer 中返回
audio_tensor = next(output)['tts_speech']
buffer = io.BytesIO()
torchaudio.save(buffer, audio_tensor, cosyvoice.sample_rate, format="wav")
buffer.seek(0)
return Response(content=buffer.read(), media_type="audio/wav")
if name == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
- 启动 HTTP 服务Bashpython3 api_server.py
- 调用 HTTP API 测试使用 curl 命令行调用：Bashcurl -X POST "http://localhost:8000/v1/tts/zero-shot" \
-F "text=你好，这是通过 HTTP API 合成的语音。" \
-F "prompt_text=参考音频的原文字内容" \
-F "prompt_wav=@/path/to/your/prompt.wav" \
--output output_api.wav
使用 Python requests 调用：Pythonimport requests
url = "http://localhost:8000/v1/tts/zero-shot"
payload = {
"text": "你好，这是通过 HTTP API 合成的语音。",
"prompt_text": "参考音频的原文字内容"
}
files = {
"prompt_wav": ("prompt.wav", open("/path/to/prompt.wav", "rb"), "audio/wav")
}
response = requests.post(url, data=payload, files=files)
with open("output_api.wav", "wb") as f:
f.write(response.content)
方式三：使用 Gradio Client（零代码修改的快速调用）如果在本地启动了 python webui.py（假设端口是 50000），Gradio 本身就会自动为你暴露一套 API 接口，你可以直接用 gradio_client 来调用：安装 Gradio 客户端工具： Bashpip install gradio_client
Python 代码调用 WebUI API：Pythonfrom gradio_client import Client, handle_file
连接本地运行的 WebUI 服务
client = Client("http://localhost:50000/")
调用零样本克隆函数（具体的 fn_index 或 api_name 可以在 http://localhost:50000/ 页脚点 "Use via API" 查看）
result = client.predict(
tts_text="你好，这是通过 Gradio API 调用的合成测试。",
prompt_text="参考音频原文字",
prompt_wav=handle_file('/path/to/prompt.wav'),
api_name="/generate_audio" # 替换为 WebUI 中实际的 API 名称
)
print("生成音频保存路径：", result)