快速开始
选择您喜欢的编程语言开始使用 API:
Python
import requests
import os
def generate_speech(text, voice="alloy", format="mp3", instructions=None):
url = "https://ttsapi.site/v1/audio/speech"
headers = {
"Content-Type": "application/json"
}
data = {
"input": text,
"voice": voice,
"response_format": format
}
# 如果提供了指令,则添加到请求中
if instructions:
data["instructions"] = instructions
response = requests.post(url, json=data, headers=headers)
if response.status_code == 200:
# 根据格式获取适当的文件扩展名
ext = format.lower()
filename = f"output.{ext}"
# 保存音频文件
with open(filename, "wb") as f:
f.write(response.content)
print(f"音频已保存为 {filename}")
return filename
else:
error = response.json()
print(f"错误: {response.status_code}, {error}")
return None
# 使用示例
text = "你好,这是一个测试。"
voice = "alloy"
format = "mp3" # 支持的格式:mp3、opus、aac、flac、wav、pcm
instructions = "请用欢快和兴奋的语气说话"
# 使用默认格式(MP3)生成语音
generate_speech(text, voice, instructions=instructions)
# 使用 WAV 格式生成语音
generate_speech(text, voice, format="wav", instructions=instructions)
JavaScript
async function generateSpeech(text, voice = 'alloy', format = 'mp3', instructions = null) {
const response = await fetch('https://ttsapi.site/v1/audio/speech', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
input: text,
voice: voice,
response_format: format,
...(instructions && { instructions })
})
});
if (response.ok) {
const blob = await response.blob();
// 创建音频元素用于播放
const audio = new Audio(URL.createObjectURL(blob));
audio.play();
// 可选:下载文件
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = `output.${format}`;
document.body.appendChild(a);
a.click();
window.URL.revokeObjectURL(url);
document.body.removeChild(a);
return blob;
} else {
const error = await response.json();
console.error('错误:', error);
throw error;
}
}
// 使用示例
const text = '你好,这是一个测试。';
const voice = 'alloy';
const format = 'mp3'; // 支持的格式:mp3、opus、aac、flac、wav、pcm
const instructions = '请用欢快和兴奋的语气说话';
// 使用默认格式(MP3)生成语音
generateSpeech(text, voice, undefined, instructions);
// 使用 WAV 格式生成语音
generateSpeech(text, voice, 'wav', instructions);
可用语音
alloy
ash
ballad
coral
echo
fable
onyx
nova
sage
shimmer
verse
API 参考
生成语音(OpenAI 兼容)
POST /v1/audio/speech
请求参数
参数 | 类型 | 必需 | 描述 |
---|---|---|---|
input | string | 是 | 要转换为语音的文本 |
voice | string | 是 | 要使用的语音(见可用语音) |
instructions | string | 否 | 发送到后端服务时映射为 "prompt" 参数。可用于指导语音情感或风格。 |
response_format | string | 否 | 音频响应的格式。支持的格式:mp3、opus、aac、flac、wav、pcm。默认为 mp3。 |
model | string | 否 | 仅用于 OpenAI 兼容性 - 完全忽略。 |
speed | number | 否 | 仅用于 OpenAI 兼容性 - 完全忽略。 |
注意: 灰色 的参数完全被服务忽略或可能导致误导行为。只有 input
、voice
response_format
和 instructions
会影响实际的 TTS 输出。
指令参数的工作原理
instructions
参数在发送到后端服务时映射为 prompt
参数。它可用于指导语音情感、语气或风格。以下是一些有效的指令示例:
- 情感指导: "请用欢快和兴奋的语气说话"
- 角色模仿: "请模仿一位睿智的老巫师说话"
- 上下文提示: "这是读给孩子的,请用温柔的语气"
- 朗读风格: "请以新闻广播的风格朗读"
提示: 请保持指令清晰简洁。过于复杂的指令可能无法被正确解释。
响应格式
API 以请求的格式返回音频,具有以下标头:
Content-Type
:根据请求的格式(例如,MP3 为 "audio/mpeg")Access-Control-Allow-Origin
:*(启用 CORS)
错误响应
状态码 | 描述 |
---|---|
400 | 缺少必需参数(input 或 voice) |
429 | 速率限制超出或队列已满。速率限制时包含 Retry-After 标头。 |
500 | 内部服务器错误 |
队列系统
API 使用队列系统高效处理多个请求:
- 最大队列大小:可通过
MAX_QUEUE_SIZE
环境变量配置(默认:100 个请求) - 请求按 FIFO(先进先出)顺序处理
- 速率限制:可通过
RATE_LIMIT_REQUESTS
和RATE_LIMIT_WINDOW
环境变量配置(默认:每个 IP 地址 60 秒内最多 30 个请求) - 可以通过
/api/queue-size
端点监控队列状态 - Web 界面每 2 秒更新一次队列状态
- 根据使用率显示队列负载状态(低/中/高)
队列状态端点
GET /api/queue-size
返回包含队列信息的 JSON:
{
"queue_size": 0, // 当前队列中的请求数
"max_queue_size": 100 // 队列最大容量
}
响应状态码
200
- 成功429
- 队列已满或超出速率限制500
- 服务器错误