TanStack AI 通过专用的 TTS 适配器提供文本到语音生成支持。本指南介绍如何使用 OpenAI 和 Gemini 提供程序将文本转换为语音音频。
文本到语音 (TTS) 由 TTS 适配器处理,这些适配器遵循与 TanStack AI 中的其他适配器相同的可树摇架构。TTS 适配器支持
import { generateSpeech } from '@tanstack/ai'
import { openaiTTS } from '@tanstack/ai-openai'
// Create a TTS adapter (uses OPENAI_API_KEY from environment)
const adapter = openaiSpeech()
// Generate speech from text
const result = await generateSpeech({
adapter: openaiTTS('tts-1'),
text: 'Hello, welcome to TanStack AI!',
voice: 'alloy',
})
// result.audio contains base64-encoded audio data
console.log(result.format) // 'mp3'
console.log(result.contentType) // 'audio/mpeg'
import { generateSpeech } from '@tanstack/ai'
import { geminiSpeech } from '@tanstack/ai-gemini'
// Create a TTS adapter (uses GOOGLE_API_KEY from environment)
const adapter = geminiSpeech()
// Generate speech from text
const result = await generateSpeech({
adapter: geminiTTS('gemini-2.5-flash-preview-tts'),
text: 'Hello from Gemini TTS!',
})
console.log(result.audio) // Base64 encoded audio
所有 TTS 适配器都支持以下常用选项
| 选项 | 类型 | 描述 |
|---|---|---|
| text | string | 要转换为语音的文本(必需) |
| voice | string | 用于生成的语音 |
| format | string | 输出音频格式(例如,“mp3”、“wav”) |
OpenAI 提供几种不同的语音
| 语音 | 描述 |
|---|---|
| alloy | 中性、平衡的语音 |
| echo | 温暖、对话式的语音 |
| fable | 富有表现力、讲故事的语音 |
| onyx | 深沉、权威的语音 |
| nova | 友好、欢快的语音 |
| shimmer | 清晰、温柔的语音 |
| ash | 冷静、沉稳的语音 |
| ballad | 旋律优美、流畅的语音 |
| coral | 明亮、充满活力的语音 |
| sage | 睿智、深思熟虑的语音 |
| verse | 诗意、有节奏的语音 |
| 格式 | 描述 |
|---|---|
| mp3 | MP3 音频(默认) |
| opus | Opus 音频(适合流式传输) |
| aac | AAC 音频 |
| flac | FLAC 音频(无损) |
| wav | WAV 音频(未压缩) |
| pcm | 原始 PCM 音频 |
const result = await generateSpeech({
adapter: openaiTTS('tts-1-hd'),
text: 'High quality speech synthesis',
voice: 'nova',
format: 'mp3',
modelOptions: {
speed: 1.0, // 0.25 to 4.0
},
})
| 选项 | 类型 | 描述 |
|---|---|---|
| speed | number | 播放速度(0.25 到 4.0,默认 1.0) |
| instructions | string | 语音风格指令(仅限 GPT-4o 音频模型) |
注意: instructions 和 stream_format 选项仅适用于 gpt-4o-audio-preview 和 gpt-4o-mini-audio-preview 模型,不适用于 tts-1 或 tts-1-hd。
TTS 结果包括
interface TTSResult {
id: string // Unique identifier for this generation
model: string // The model used
audio: string // Base64-encoded audio data
format: string // Audio format (e.g., "mp3")
contentType: string // MIME type (e.g., "audio/mpeg")
duration?: number // Duration in seconds (if available)
}
// Convert base64 to audio and play
function playAudio(result: TTSResult) {
const audioData = atob(result.audio)
const bytes = new Uint8Array(audioData.length)
for (let i = 0; i < audioData.length; i++) {
bytes[i] = audioData.charCodeAt(i)
}
const blob = new Blob([bytes], { type: result.contentType })
const url = URL.createObjectURL(blob)
const audio = new Audio(url)
audio.play()
// Clean up when done
audio.onended = () => URL.revokeObjectURL(url)
}
import { writeFile } from 'fs/promises'
async function saveAudio(result: TTSResult, filename: string) {
const audioBuffer = Buffer.from(result.audio, 'base64')
await writeFile(filename, audioBuffer)
console.log(`Saved to ${filename}`)
}
// Usage
const result = await generateSpeech({
adapter: openaiTTS('tts-1'),
text: 'Hello world!',
})
await saveAudio(result, 'output.mp3')
| 模型 | 质量 | 速度 | 用例 |
|---|---|---|---|
| tts-1 | 标准 | 快速 | 实时应用 |
| tts-1-hd | 高 | 较慢 | 制作音频 |
| gpt-4o-audio-preview | 最高 | 可变 | 高级语音控制 |
| gpt-4o-mini-audio-preview | 高 | 快速 | 平衡的质量/速度 |
| 模型 | 状态 | 注意事项 |
|---|---|---|
| gemini-2.5-flash-preview-tts | 实验版 | 可能需要 Live API 才能获得完整功能 |
try {
const result = await generateSpeech({
adapter: openaiTTS('tts-1'),
text: 'Hello!',
})
} catch (error) {
if (error.message.includes('exceeds maximum length')) {
console.error('Text is too long (max 4096 characters)')
} else if (error.message.includes('Speed must be between')) {
console.error('Invalid speed value')
} else {
console.error('TTS error:', error.message)
}
}
TTS 适配器使用与其他适配器相同的环境变量
对于生产用途或需要显式控制时
import { createOpenaiTTS } from '@tanstack/ai-openai'
import { createGeminiTTS } from '@tanstack/ai-gemini'
// OpenAI
const openaiAdapter = createOpenaiTTS('your-openai-api-key')
// Gemini
const geminiAdapter = createGeminiTTS('your-google-api-key')
文本长度:OpenAI TTS 每请求支持最多 4096 个字符。对于更长的内容,请将其拆分为块。
语音选择:选择适合您内容的语音——使用 onyx 用于权威内容,使用 nova 用于友好互动。
格式选择:对于一般用途,使用 mp3,对于流式传输,使用 opus,对于进一步处理,使用 wav。
缓存:缓存生成的音频以避免重新生成相同的内容。
错误处理:始终优雅地处理错误,尤其是在面向用户的应用程序中。