VoxCPM2 TTS API 用户对接文档

接口简介

VoxCPM2 TTS API 用于将文本合成为语音，支持文本转语音、声音风格控制、参考音频克隆等能力。

接口地址：POST http://<服务地址>:5022/api/tts

请求格式：application/json

返回格式：application/json

返回音频：WAV 音频的 Base64 字符串

请求参数

请求体字段如下：

text：string，必填。需要合成为语音的目标文本，不能为空。

prompt：string，选填。控制提示词，用于描述音色、情绪、语速、语气、方言等。

audio：string，选填。参考音频 Base64 字符串，支持纯 Base64，也支持 data:audio/wav;base64,... 格式。

reference_text：string，选填。参考音频对应的文字内容，用于极致克隆模式。

请求体 JSON 字符串示例：

{"text":"要合成的目标文本","prompt":"控制提示词，可选","audio":"参考音频的 base64 字符串，可选","reference_text":"参考音频对应文本，可选"}

使用模式

文本转语音

只传 text，其他字段传空字符串。

请求字符串：

{"text":"欢迎使用 VoxCPM2 语音合成服务。","prompt":"","audio":"","reference_text":""}

声音设计

传 text 和 prompt，不传参考音频。

请求字符串：

{"text":"欢迎使用 VoxCPM2 语音合成服务。","prompt":"年轻女性，声音温柔甜美，语速适中","audio":"","reference_text":""}

可控克隆

传 text、prompt 和 audio。

audio 需要传参考音频文件的 Base64 字符串，不是文件路径。

请求字符串：

{"text":"今天的会议将在下午三点开始，请大家准时参加。","prompt":"正式、清晰、语速稍慢","audio":"UklGRiQAAABXQVZFZm10IBAAAAABAAEA...","reference_text":""}

极致克隆

传 text 和 audio，prompt 传空字符串。

建议同时传入 reference_text，也就是参考音频中实际说的文字。如果不传，服务端会尝试自动识别。

请求字符串：

{"text":"接下来我们继续介绍系统的核心功能。","prompt":"","audio":"UklGRiQAAABXQVZFZm10IBAAAAABAAEA...","reference_text":"大家好，欢迎来到今天的产品介绍。"}

返回参数

成功返回字符串：

{"status":"success","sample_rate":48000,"audio":"UklGRiQAAABXQVZFZm10IBAAAAABAAEA..."}

成功返回字段说明：

status：请求状态，成功时为 success。

sample_rate：音频采样率。

audio：生成后的 WAV 音频 Base64 字符串。

失败返回字符串：

{"status":"error","message":"text cannot be empty"}

失败返回字段说明：

status：请求状态，失败时为 error。

message：错误原因。

常见错误：

text cannot be empty：text 参数为空。

audio is not valid base64：audio 不是合法 Base64 字符串。

inference failed：服务端推理失败。

Python 调用示例

普通文本转语音

以下为可复制的 Python 示例。由于部分 README 平台不支持代码块，这里以普通文本形式展示：

import base64

import requests

url = "http://<服务地址>:5022/api/tts"

payload = {"text":"欢迎使用 VoxCPM2 语音合成服务。","prompt":"年轻女性，声音温柔甜美，语速适中","audio":"","reference_text":""}

response = requests.post(url, json=payload, timeout=300)

response.raise_for_status()

result = response.json()

if result["status"] != "success":

raise RuntimeError(result.get("message", "TTS request failed"))

wav_bytes = base64.b64decode(result["audio"])

with open("output.wav", "wb") as f:

f.write(wav_bytes)

参考音频克隆

以下为可复制的 Python 示例。reference.wav 是本地参考音频文件：

import base64

import requests

url = "http://<服务地址>:5022/api/tts"

with open("reference.wav", "rb") as f:

reference_audio = base64.b64encode(f.read()).decode("utf-8")

payload = {"text":"这是一段通过参考音频克隆生成的新语音。","prompt":"自然、稳定、语速适中","audio":reference_audio,"reference_text":""}

response = requests.post(url, json=payload, timeout=300)

response.raise_for_status()

result = response.json()

if result["status"] != "success":

raise RuntimeError(result.get("message", "TTS request failed"))

with open("clone_output.wav", "wb") as f:

f.write(base64.b64decode(result["audio"]))

JavaScript 调用示例

以下为浏览器端播放示例，以普通文本形式展示：

async function requestTTS() {

const response = await fetch("http://<服务地址>:5022/api/tts", {

method: "POST",

headers: {"Content-Type": "application/json"},

body: JSON.stringify({"text":"欢迎使用 VoxCPM2 语音合成服务。","prompt":"年轻女性，声音温柔甜美，语速适中","audio":"","reference_text":""})

});

const result = await response.json();

if (result.status !== "success") {

throw new Error(result.message || "TTS request failed");

}

const binary = atob(result.audio);

const bytes = new Uint8Array(binary.length);

for (let i = 0; i < binary.length; i++) {

bytes[i] = binary.charCodeAt(i);

}

const blob = new Blob([bytes], {type: "audio/wav"});

const audioUrl = URL.createObjectURL(blob);

new Audio(audioUrl).play();

}

注意事项

text 不能为空。

audio 需要传 Base64 字符串，不是文件路径。

返回的 audio 是 WAV 文件 Base64，需要解码后保存或播放。

参考音频建议使用清晰的 WAV 音频。

极致克隆模式下，prompt 必须传空字符串。