tts-universal

name	tts-universal
description	统一 TTS 适配层，支持 6+ TTS 服务商（MiniMax、ElevenLabs、火山引擎、Edge TTS、阿里 Qwen3、腾讯混元）。 提供统一接口，自动处理时间戳格式转换。 触发词： - "TTS"、"文字转语音"、"语音合成" - "MiniMax TTS"、"Edge TTS"、"火山引擎" - 选择 TTS 服务商时 使用场景： - 科普视频配音 - 教程讲解配音 - 多语言语音生成

tts-universal

统一 TTS 适配层，支持 6+ TTS 服务商。

支持的服务商

ID	服务商	语言	特色	免费额度
edge	Edge TTS	多语言	完全免费，零配置	无限
minimax	MiniMax	中文	音色克隆，高速	按量付费
volcengine	火山引擎	中文	公式朗读支持	有免费
elevenlabs	ElevenLabs	英文	多语言高质量	$0.10/千字
aliyun	阿里 Qwen3	中英	高额度	50万字/月
tencent	腾讯混元	中文	企业级	按量付费

快速开始

1. 安装依赖

# 基础依赖（所有适配器都需要）
pip install requests

# Edge TTS（免费，无需 API Key）
pip install edge-tts

# 其他服务商需要相应的 API Key

2. 配置 API Key

import os

# 方式 1：环境变量
os.environ["MINIMAX_API_KEY"] = "your-api-key"
os.environ["ELEVENLABS_API_KEY"] = "your-api-key"

# 方式 2：初始化时传入
from tts_universal import TTSManager
manager = TTSManager({
    "minimax": "your-api-key",
    "elevenlabs": "your-api-key",
})

3. 生成音频

from tts_universal import TTSManager

manager = TTSManager()

# 使用 Edge TTS（免费）
result = manager.synthesize(
    text="卷积神经网络是计算机视觉的核心技术。",
    provider="edge",
    voice_id="zh-CN-YunyangNeural"
)

print(f"音频路径: {result.audio_path}")
print(f"时长: {result.duration_ms}ms")
print(f"时间戳数量: {len(result.timestamps)}")

统一接口

TTSManager

class TTSManager:
    def __init__(self, api_keys: Dict[str, str] = None)

    def synthesize(
        self,
        text: str,
        provider: str = "edge",
        voice_id: str = None,
        output_filename: str = None,
        **kwargs
    ) -> TTSResult

    def list_providers(self) -> List[Dict]
    def get_adapter(self, provider: str) -> TTSAdapter

TTSResult

@dataclass
class TTSResult:
    audio_path: str          # 音频文件路径
    audio_base64: str       # base64 编码音频
    duration_ms: int         # 总时长（毫秒）
    timestamps: List[Timestamp]  # 时间戳列表
    provider: str            # 服务商 ID
    text: str               # 原始文本

@dataclass
class Timestamp:
    text: str    # 单字或单词
    begin: int   # 开始时间（毫秒）
    end: int     # 结束时间（毫秒）

推荐音色

Edge TTS（免费）

Voice ID	名称	风格
zh-CN-YunyangNeural	云扬	专业播音腔（推荐）
zh-CN-XiaoxiaoNeural	晓晓	温暖自然
zh-CN-YunxiNeural	云希	阳光少年
en-US-JennyNeural	Jenny	英文女声
en-US-GuyNeural	Guy	英文男声

MiniMax

Voice ID	名称
female_calm	女声-温柔
male_broadcast	男声-播音
female_excited	女声-活泼
male_youth	男声-青年

火山引擎

Voice ID	名称
zh_female_shuangkuai	女声-爽快
zh_male_shaonian	男声-少年
zh_female_yuanqi	女声-元气

时间戳使用

时间戳用于 Remotion 中的音画同步：

import { useCurrentFrame, useVideoConfig } from "remotion";

const TTSPlayer: React.FC<{
  audioFile: string;
  timestamps: Timestamp[];
  text: string;
}> = ({ audioFile, timestamps, text }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const currentTimeMs = (frame / fps) * 1000;

  const activeIndex = timestamps.findIndex(
    ts => currentTimeMs >= ts.begin && currentTimeMs <= ts.end
  );

  return (
    <>
      <Audio src={staticFile(audioFile)} />
      <div className="subtitle">
        {text.split("").map((char, i) => (
          <span key={i} style={{
            opacity: i === activeIndex ? 1 : i < activeIndex ? 0.5 : 0.3,
            color: i === activeIndex ? "#FFFF00" : "#FFFFFF"
          }}>
            {char}
          </span>
        ))}
      </div>
    </>
  );
};

错误处理

from tts_universal.exceptions import (
    TTSError,
    TTSAuthError,
    TTSRateLimitError,
    TTSTimeoutError
)

try:
    result = manager.synthesize(text, provider="minimax")
except TTSAuthError:
    print("API Key 无效")
except TTSRateLimitError:
    print("请求过于频繁，请稍后重试")
except TTSTimeoutError:
    print("生成超时")

文件结构

tts-universal/
├── SKILL.md
├── __init__.py
├── manager.py          # 统一管理器
├── exceptions.py       # 异常定义
└── adapters/
    ├── __init__.py
    ├── base.py         # 适配器基类
    ├── edge.py         # Edge TTS（免费）
    ├── minimax.py      # MiniMax
    ├── elevenlabs.py   # ElevenLabs
    ├── volcengine.py   # 火山引擎
    ├── aliyun.py       # 阿里 Qwen3
    └── tencent.py      # 腾讯混元

参考资源

• API_TTS.md
• Edge TTS: https://github.com/rany2/edge-tts
• MiniMax API: https://platform.minimaxi.com/document
• ElevenLabs: https://elevenlabs.io/docs/api-reference