快速开始

选择您喜欢的编程语言开始使用 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 兼容性 - 完全忽略。

注意: 灰色 的参数完全被服务忽略或可能导致误导行为。只有 inputvoice response_formatinstructions 会影响实际的 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_REQUESTSRATE_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 - 服务器错误