快速开始

选择您喜欢的编程语言开始使用 API：

Python 
import requests

url = "https://ttsapi.site/v1/audio/speech"
headers = {
    "Content-Type": "application/json"
}
data = {
    "input": "你好，这是一个测试。",
    "voice": "alloy",
    "instructions": "请用欢快和兴奋的语气说话"  // 可选
}

response = requests.post(url, json=data, headers=headers)
if response.status_code == 200:
    # 保存音频文件 - 始终为 MP3 格式
    with open("output.mp3", "wb") as f:
        f.write(response.content)
    print("音频已保存为 output.mp3")
else:
    print(f"错误: {response.status_code}, {response.json()}")
JavaScript 
async function generateSpeech() {
    const response = await fetch('https://ttsapi.site/v1/audio/speech', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            input: '你好，这是一个测试。',
            voice: 'alloy',
            instructions: '请用欢快和兴奋的语气说话'  // 可选
        })
    });

    if (response.ok) {
        // 始终为 MP3 格式
        const blob = await response.blob();
        const audio = new Audio(URL.createObjectURL(blob));
        audio.play();
    } else {
        const error = await response.json();
        console.error('错误:', error);
    }
}

可用语音

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 否 仅用于 OpenAI 兼容性 - 仅更改 Content-Type 标头，不改变实际音频格式。可能导致错误的 Content-Type 标头。音频始终为 MP3。
model string 否 仅用于 OpenAI 兼容性 - 完全忽略。
speed number 否 仅用于 OpenAI 兼容性 - 完全忽略。

注意： 灰色 的参数完全被服务忽略或可能导致误导行为。只有 input、voice 和 instructions 会影响实际的 TTS 输出。

指令参数的工作原理

instructions 参数在发送到后端服务时映射为 prompt 参数。它可用于指导语音情感、语气或风格。以下是一些有效的指令示例：

  • 情感指导： "请用欢快和兴奋的语气说话"
  • 角色模仿： "请模仿一位睿智的老巫师说话"
  • 上下文提示： "这是读给孩子的，请用温柔的语气"
  • 朗读风格： "请以新闻广播的风格朗读"

提示： 请保持指令清晰简洁。过于复杂的指令可能无法被正确解释。

响应格式

API 始终返回二进制 MP3 音频文件，具有以下标头：

  • Content-Type: "audio/mpeg"
  • Access-Control-Allow-Origin: "*" (启用 CORS)

重要： 虽然 response_format 参数可能会更改响应中的 Content-Type 标头，但它不会实际转换音频格式。音频始终从上游服务以 MP3 格式返回。

错误响应

状态码 描述
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 - 服务器错误

队列负载指示器

  • 低负载 (0-40%)：绿色指示器，适合发送新请求
  • 中负载 (40-75%)：黄色/橙色指示器，可能会有延迟
  • 高负载 (75-100%)：红色指示器，预计会有明显延迟