README.zh.md

TTSFM - 文本转语音API客户端

Language / 语言: English | 中文

Star历史

🎤 现代化、免费的文本转语音API客户端，兼容OpenAI

TTSFM为文本转语音生成提供同步和异步Python客户端，使用逆向工程的openai.fm服务。无需API密钥 - 完全免费使用！

✨ 主要特性

• 🆓 完全免费 - 使用逆向工程的openai.fm服务（无需API密钥）
• 🎯 OpenAI兼容 - OpenAI TTS API的直接替代品（/v1/audio/speech）
• ⚡ 异步和同步 - 提供asyncio和同步客户端
• 🗣️ 11种声音 - 所有OpenAI兼容的声音（alloy、echo、fable、onyx、nova、shimmer等）
• 🎵 6种音频格式 - 支持MP3、WAV、OPUS、AAC、FLAC、PCM
• 🐳 Docker就绪 - 一键部署，包含Web界面
• 🌐 Web界面 - 用于测试声音和格式的交互式试用平台
• 🔧 CLI工具 - 用于快速TTS生成的命令行界面
• 📦 类型提示 - 完整的类型注解支持，提供更好的IDE体验
• 🛡️ 错误处理 - 全面的异常层次结构和重试逻辑
• ✨ 自动合并 - 自动处理长文本，无缝音频合并
• 📊 文本验证 - 自动文本长度验证和分割
• 🔐 API密钥保护 - 可选的OpenAI兼容身份验证，用于安全部署

📦 安装

快速安装

pip install ttsfm

安装选项

# 基础安装（仅同步客户端）
pip install ttsfm

# 包含Web应用支持
pip install ttsfm[web]

# 包含开发工具
pip install ttsfm[dev]

# 包含文档工具
pip install ttsfm[docs]

# 安装所有可选依赖
pip install ttsfm[web,dev,docs]

系统要求

• Python: 3.8+（在3.8、3.9、3.10、3.11、3.12上测试）
• 操作系统: Windows、macOS、Linux
• 依赖: requests、aiohttp、fake-useragent

🚀 快速开始

🐳 Docker（推荐）

运行带有Web界面和OpenAI兼容API的TTSFM：

# 使用GitHub Container Registry
docker run -p 8000:8000 ghcr.io/dbccccccc/ttsfm:latest

# 使用Docker Hub
docker run -p 8000:8000 dbcccc/ttsfm:latest

可用端点：

• 🌐 Web界面: http://localhost:8000
• 🔗 OpenAI API: http://localhost:8000/v1/audio/speech
• 📊 健康检查: http://localhost:8000/api/health

测试API：

curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini-tts","input":"你好世界！","voice":"alloy"}' \
  --output speech.mp3

📦 Python包

同步客户端

from ttsfm import TTSClient, Voice, AudioFormat

# 创建客户端（使用免费的openai.fm服务）
client = TTSClient()

# 生成语音
response = client.generate_speech(
    text="你好！这是TTSFM - 一个免费的TTS服务。",
    voice=Voice.CORAL,
    response_format=AudioFormat.MP3
)

# 保存音频文件
response.save_to_file("output")  # 保存为output.mp3

# 或获取原始音频数据
audio_bytes = response.audio_data
print(f"生成了 {len(audio_bytes)} 字节的音频")

异步客户端

import asyncio
from ttsfm import AsyncTTSClient, Voice

async def generate_speech():
    async with AsyncTTSClient() as client:
        response = await client.generate_speech(
            text="异步TTS生成！",
            voice=Voice.NOVA
        )
        response.save_to_file("async_output")

# 运行异步函数
asyncio.run(generate_speech())

长文本处理（Python包）

对于需要精细控制文本分割的开发者：

from ttsfm import TTSClient, Voice, AudioFormat

# 创建客户端
client = TTSClient()

# 从长文本生成语音（为每个片段创建单独的文件）
responses = client.generate_speech_long_text(
    text="超过4096字符的很长文本...",
    voice=Voice.ALLOY,
    response_format=AudioFormat.MP3,
    max_length=2000,
    preserve_words=True
)

# 将每个片段保存为单独的文件
for i, response in enumerate(responses, 1):
    response.save_to_file(f"part_{i:03d}")  # 保存为part_001.mp3、part_002.mp3等

print(f"从长文本生成了 {len(responses)} 个音频文件")

OpenAI Python客户端兼容性

from openai import OpenAI

# 指向TTSFM Docker容器（默认不需要API密钥）
client = OpenAI(
    api_key="not-needed",  # TTSFM默认免费
    base_url="http://localhost:8000/v1"
)

# 启用API密钥保护时
client_with_auth = OpenAI(
    api_key="your-secret-api-key",  # 您的TTSFM API密钥
    base_url="http://localhost:8000/v1"
)

# 生成语音（与OpenAI完全相同）
response = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="alloy",
    input="来自TTSFM的问候！"
)

response.stream_to_file("output.mp3")

长文本自动合并功能

TTSFM通过新的自动合并功能自动处理长文本（>4096字符）：

from openai import OpenAI

client = OpenAI(
    api_key="not-needed",
    base_url="http://localhost:8000/v1"
)

# 长文本自动分割并合并为单个音频文件
long_article = """
您的很长的文章或文档内容在这里...
这可以是数千字符长，TTSFM将
自动将其分割成片段，为每个片段生成音频，
并将它们合并成一个无缝的音频文件。
""" * 100  # 使其真的很长

# 这可以无缝工作 - 无需手动分割！
response = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="nova",
    input=long_article,
    # auto_combine=True 是默认值
)

response.stream_to_file("long_article.mp3")  # 单个合并文件！

# 禁用自动合并以严格兼容OpenAI
response = client.audio.speech.create(
    model="gpt-4o-mini-tts",
    voice="nova",
    input="仅短文本",
    auto_combine=False  # 如果文本>4096字符将出错
)

🖥️ 命令行界面

# 基本用法
ttsfm "你好，世界！" --output hello.mp3

# 指定声音和格式
ttsfm "你好，世界！" --voice nova --format wav --output hello.wav

# 从文件读取
ttsfm --text-file input.txt --output speech.mp3

# 自定义服务URL
ttsfm "你好，世界！" --url http://localhost:7000 --output hello.mp3

# 列出可用声音
ttsfm --list-voices

# 获取帮助
ttsfm --help

⚙️ 配置

TTSFM自动使用免费的openai.fm服务 - 默认情况下无需配置或API密钥！

环境变量

变量	默认值	描述
REQUIRE_API_KEY	false	启用API密钥保护
TTSFM_API_KEY	None	您的秘密API密钥
HOST	localhost	服务器主机
PORT	8000	服务器端口
DEBUG	false	调试模式

Python客户端配置

from ttsfm import TTSClient

# 默认客户端（使用openai.fm，无需API密钥）
client = TTSClient()

# 自定义配置
client = TTSClient(
    base_url="https://www.openai.fm",  # 默认
    timeout=30.0,                     # 请求超时
    max_retries=3,                    # 重试次数
    verify_ssl=True                   # SSL验证
)

# 用于带有API密钥保护的TTSFM服务器
protected_client = TTSClient(
    base_url="http://localhost:8000",
    api_key="your-ttsfm-api-key"
)

# 用于其他自定义TTS服务
custom_client = TTSClient(
    base_url="http://your-tts-service.com",
    api_key="your-api-key-if-needed"
)

🗣️ 可用声音

TTSFM支持所有11种OpenAI兼容声音：

声音	描述	最适合
alloy	平衡且多功能	通用目的，中性语调
ash	清晰且清楚	专业，商务内容
ballad	流畅且优美	讲故事，有声读物
coral	温暖且友好	客户服务，教程
echo	共鸣且清晰	公告，演示
fable	富有表现力且动态	创意内容，娱乐
nova	明亮且充满活力	营销，积极内容
onyx	深沉且权威	新闻，严肃内容
sage	智慧且稳重	教育，信息性
shimmer	轻盈且飘逸	休闲，对话式
verse	有节奏且流畅	诗歌，艺术内容

from ttsfm import Voice

# 使用枚举值
response = client.generate_speech("你好！", voice=Voice.CORAL)

# 或使用字符串值
response = client.generate_speech("你好！", voice="coral")

# 测试不同声音
for voice in Voice:
    response = client.generate_speech(f"这是{voice.value}声音", voice=voice)
    response.save_to_file(f"test_{voice.value}")

🎵 音频格式

TTSFM支持6种音频格式，具有不同的质量和压缩选项：

格式	扩展名	质量	文件大小	使用场景
mp3	.mp3	良好	小	Web、移动应用、通用使用
opus	.opus	优秀	小	Web流媒体、VoIP
aac	.aac	良好	中等	Apple设备、流媒体
flac	.flac	无损	大	高质量存档
wav	.wav	无损	大	专业音频
pcm	.pcm	原始	大	音频处理

使用示例

from ttsfm import TTSClient, AudioFormat

client = TTSClient()

# 生成不同格式
formats = [
    AudioFormat.MP3,   # 最常见
    AudioFormat.OPUS,  # 最佳压缩
    AudioFormat.AAC,   # Apple兼容
    AudioFormat.FLAC,  # 无损
    AudioFormat.WAV,   # 未压缩
    AudioFormat.PCM    # 原始音频
]

for fmt in formats:
    response = client.generate_speech(
        text="测试音频格式",
        response_format=fmt
    )
    response.save_to_file(f"test.{fmt.value}")

格式选择指南

• 选择MP3用于：

  • Web应用
  • 移动应用
  • 较小的文件大小
  • 通用音频

• 选择OPUS用于：

  • Web流媒体
  • VoIP应用
  • 最佳压缩比
  • 实时音频

• 选择AAC用于：

  • Apple设备
  • 流媒体服务
  • 良好的质量/大小平衡

• 选择FLAC用于：

  • 存档目的
  • 无损压缩
  • 专业工作流程

• 选择WAV用于：

  • 专业音频制作
  • 最大兼容性
  • 当文件大小不是问题时

• 选择PCM用于：

  • 音频处理
  • 原始音频数据
  • 自定义应用

注意：库会自动优化请求，为您选择的格式提供最佳质量。文件总是根据音频格式以正确的扩展名保存。

🌐 Web界面

TTSFM包含一个美观的Web界面用于测试和实验：

功能：

• 🎮 交互式试用平台 - 实时测试声音和格式
• 📝 文本验证 - 字符计数和长度验证
• 🎛️ 高级选项 - 声音指令，自动分割长文本
• 📊 音频播放器 - 内置播放器，显示时长和文件大小信息
• 📥 下载支持 - 下载单个或批量音频文件
• 🎲 随机文本 - 生成随机示例文本进行测试
• 📱 响应式设计 - 在桌面、平板和移动设备上工作

访问地址：http://localhost:8000（运行Docker容器时）

🔗 API端点

运行Docker容器时，这些端点可用：

端点	方法	描述
/	GET	Web界面
/playground	GET	交互式TTS试用平台
/v1/audio/speech	POST	OpenAI兼容的TTS API
/v1/models	GET	列出可用模型
/api/health	GET	健康检查端点
/api/voices	GET	列出可用声音
/api/formats	GET	列出支持的音频格式
/api/validate-text	POST	验证文本长度

OpenAI兼容API

# 生成语音（短文本） - 默认不需要API密钥
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "input": "你好，这是一个测试！",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

# 使用API密钥生成语音（启用保护时）
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-api-key" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "input": "你好，这是一个测试！",
    "voice": "alloy",
    "response_format": "mp3"
  }' \
  --output speech.mp3

# 使用自动合并从长文本生成语音（默认行为）
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "input": "这是一个超过4096字符限制的很长文本...",
    "voice": "alloy",
    "response_format": "mp3",
    "auto_combine": true
  }' \
  --output long_speech.mp3

# 不使用自动合并从长文本生成语音（如果文本>4096字符将返回错误）
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini-tts",
    "input": "您的文本在这里...",
    "voice": "alloy",
    "response_format": "mp3",
    "auto_combine": false
  }' \
  --output speech.mp3

# 列出模型
curl http://localhost:8000/v1/models

# 健康检查
curl http://localhost:8000/api/health

新参数：auto_combine

TTSFM通过可选的auto_combine参数扩展了OpenAI API：

• **auto_combine**（布尔值，可选，默认：true）
  • 当为true时：自动将长文本（>4096字符）分割成片段，为每个片段生成音频，并将它们合并成一个无缝的音频文件
  • 当为false时：如果文本超过4096字符限制则返回错误（标准OpenAI行为）
  • 好处：无需手动管理长内容的文本分割或音频文件合并

🐳 Docker部署

快速开始

# 使用默认设置运行（无需API密钥）
docker run -p 8000:8000 ghcr.io/dbccccccc/ttsfm:latest

# 启用API密钥保护运行
docker run -p 8000:8000 \
  -e REQUIRE_API_KEY=true \
  -e TTSFM_API_KEY=your-secret-api-key \
  ghcr.io/dbccccccc/ttsfm:latest

# 使用自定义端口运行
docker run -p 3000:8000 ghcr.io/dbccccccc/ttsfm:latest

# 后台运行
docker run -d -p 8000:8000 --name ttsfm ghcr.io/dbccccccc/ttsfm:latest

Docker Compose

version: '3.8'
services:
  ttsfm:
    image: ghcr.io/dbccccccc/ttsfm:latest
    ports:
      - "8000:8000"
    environment:
      - PORT=8000
      # 可选：启用API密钥保护
      - REQUIRE_API_KEY=false
      - TTSFM_API_KEY=your-secret-api-key-here
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

可用镜像

注册表	镜像	描述
GitHub Container Registry	ghcr.io/dbccccccc/ttsfm:latest	最新稳定版本
Docker Hub	dbcccc/ttsfm:latest	Docker Hub镜像
GitHub Container Registry	ghcr.io/dbccccccc/ttsfm:v3.2.2	特定版本

🛠️ 高级用法

错误处理

from ttsfm import TTSClient, TTSException, APIException, NetworkException

client = TTSClient()

try:
    response = client.generate_speech("你好，世界！")
    response.save_to_file("output")
except NetworkException as e:
    print(f"网络错误：{e}")
except APIException as e:
    print(f"API错误：{e}")
except TTSException as e:
    print(f"TTS错误：{e}")

文本验证和分割

from ttsfm.utils import validate_text_length, split_text_by_length

# 验证文本长度
text = "您的长文本在这里..."
is_valid, length = validate_text_length(text, max_length=4096)

if not is_valid:
    # 将长文本分割成片段
    chunks = split_text_by_length(text, max_length=4000)

    # 为每个片段生成语音
    for i, chunk in enumerate(chunks):
        response = client.generate_speech(chunk)
        response.save_to_file(f"output_part_{i}")

自定义请求头和用户代理

from ttsfm import TTSClient

# 客户端自动使用真实的请求头
client = TTSClient()

# 请求头包括：
# - 真实的User-Agent字符串
# - 音频内容的Accept头
# - 连接保持活跃
# - 压缩的Accept-Encoding

🔧 开发

本地开发

# 克隆仓库
git clone https://github.com/dbccccccc/ttsfm.git
cd ttsfm

# 以开发模式安装
pip install -e .[dev]

# 运行测试
pytest

# 运行Web应用
cd ttsfm-web
python app.py

构建Docker镜像

# 构建镜像
docker build -t ttsfm:local .

# 运行本地镜像
docker run -p 8000:8000 ttsfm:local

贡献

1. Fork仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开Pull Request

📊 性能

基准测试

• 延迟：典型文本约1-3秒（取决于openai.fm服务）
• 吞吐量：异步客户端支持并发请求
• 文本限制：使用自动合并无限制！自动处理任何长度的文本
• 音频质量：与OpenAI相当的高质量合成

优化技巧

# 使用异步客户端获得更好的性能
async with AsyncTTSClient() as client:
    # 并发处理多个请求
    tasks = [
        client.generate_speech(f"文本 {i}")
        for i in range(10)
    ]
    responses = await asyncio.gather(*tasks)

# 重用客户端实例
client = TTSClient()
for text in texts:
    response = client.generate_speech(text)  # 重用连接

🔐 API密钥保护（可选）

TTSFM支持OpenAI兼容的API密钥身份验证用于安全部署：

快速设置

# 启用API密钥保护
export REQUIRE_API_KEY=true
export TTSFM_API_KEY=your-secret-api-key

# 启用保护运行
docker run -p 8000:8000 \
  -e REQUIRE_API_KEY=true \
  -e TTSFM_API_KEY=your-secret-api-key \
  ghcr.io/dbccccccc/ttsfm:latest

身份验证方法

API密钥以OpenAI兼容格式接受：

from openai import OpenAI

# 标准OpenAI格式
client = OpenAI(
    api_key="your-secret-api-key",
    base_url="http://localhost:8000/v1"
)

# 或使用curl
curl -X POST http://localhost:8000/v1/audio/speech \
  -H "Authorization: Bearer your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini-tts","input":"你好！","voice":"alloy"}'

功能

• 🔑 OpenAI兼容：使用标准Authorization: Bearer头
• 🛡️ 多种认证方法：头部、查询参数或JSON正文
• 🎛️ 可配置：通过环境变量轻松启用/禁用
• 📊 安全日志：跟踪无效访问尝试
• 🌐 Web界面：自动API密钥字段检测

受保护的端点

启用时，这些端点需要身份验证：

• POST /v1/audio/speech - 语音生成
• POST /api/generate - 传统语音生成
• POST /api/generate-combined - 合并语音生成

公共端点

这些端点无需身份验证即可访问：

• GET / - Web界面
• GET /playground - 交互式试用平台
• GET /api/health - 健康检查
• GET /api/voices - 可用声音
• GET /api/formats - 支持的格式

🔒 安全和隐私

• 可选API密钥：默认免费，需要时安全
• 无数据存储：音频按需生成，不存储
• HTTPS支持：到TTS服务的安全连接
• 无跟踪：TTSFM不收集或存储用户数据
• 开源：完整源代码可供审计

📋 更新日志

查看CHANGELOG.md了解详细版本历史。

最新更改（v3.2.3）

• ✨ 默认自动合并：长文本现在自动分割并合并为单个音频文件
• 🔄 统一API端点：单个/v1/audio/speech端点智能处理短文本和长文本
• 🎛️ 可配置行为：新的auto_combine参数（默认：true）提供完全控制
• 🤖 增强OpenAI兼容性：具有智能长文本处理的直接替代品
• 📊 丰富响应头：X-Auto-Combine、X-Chunks-Combined和处理元数据
• 🧹 简化Web界面：移除传统批处理，提供更清洁的用户体验
• 📖 简化文档：Web文档强调现代自动合并方法
• 🎮 增强试用平台：专注于自动合并功能的清洁界面
• 🔐 API密钥保护：用于安全部署的可选OpenAI兼容身份验证
• 🛡️ 安全功能：具有详细日志的全面访问控制

🤝 支持和社区

• 🐛 错误报告：GitHub Issues
• 💬 讨论：GitHub Discussions
• 👤 作者：@dbcccc
• ⭐ 为项目加星：如果您觉得TTSFM有用，请在GitHub上为其加星！

📄 许可证

MIT许可证 - 详见LICENSE文件。

🙏 致谢

• OpenAI：原始TTS API设计
• openai.fm：提供免费TTS服务
• 社区：感谢所有帮助改进TTSFM的用户和贡献者

---

TTSFM - 免费文本转语音API，兼容OpenAI

---

📖 文档

• 🇺🇸 English: README.md
• 🇨🇳 中文: README.zh.md

由@dbcccc用❤️制作