文档
CodeRabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
CodeRabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
PowerSync
Sentry
Railway
Prisma
Strapi
Unkey
类引用
函数引用
接口引用
类型别名引用
变量引用
指南

文本转语音

文本到语音 (TTS)

TanStack AI 通过专用的 TTS 适配器提供文本到语音生成支持。本指南介绍如何使用 OpenAI 和 Gemini 提供程序将文本转换为语音音频。

概述

文本到语音 (TTS) 由 TTS 适配器处理,这些适配器遵循与 TanStack AI 中的其他适配器相同的可树摇架构。TTS 适配器支持

  • OpenAI:TTS-1、TTS-1-HD 和支持音频的 GPT-4o 模型
  • Gemini:Gemini 2.5 Flash TTS(实验版)

基本用法

OpenAI 文本到语音

typescript
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'

Gemini 文本到语音(实验版)

typescript
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 适配器都支持以下常用选项

选项类型描述
textstring要转换为语音的文本(必需)
voicestring用于生成的语音
formatstring输出音频格式(例如,“mp3”、“wav”)

OpenAI 语音选项

OpenAI 提供几种不同的语音

语音描述
alloy中性、平衡的语音
echo温暖、对话式的语音
fable富有表现力、讲故事的语音
onyx深沉、权威的语音
nova友好、欢快的语音
shimmer清晰、温柔的语音
ash冷静、沉稳的语音
ballad旋律优美、流畅的语音
coral明亮、充满活力的语音
sage睿智、深思熟虑的语音
verse诗意、有节奏的语音

OpenAI 格式选项

格式描述
mp3MP3 音频(默认)
opusOpus 音频(适合流式传输)
aacAAC 音频
flacFLAC 音频(无损)
wavWAV 音频(未压缩)
pcm原始 PCM 音频

模型选项

OpenAI 模型选项

typescript
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
  },
})
选项类型描述
speednumber播放速度(0.25 到 4.0,默认 1.0)
instructionsstring语音风格指令(仅限 GPT-4o 音频模型)

注意: instructionsstream_format 选项仅适用于 gpt-4o-audio-previewgpt-4o-mini-audio-preview 模型,不适用于 tts-1tts-1-hd

响应格式

TTS 结果包括

typescript
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)
}

在浏览器中播放音频

typescript
// 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)
}

将音频保存到文件(Node.js)

typescript
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')

模型可用性

OpenAI 模型

模型质量速度用例
tts-1标准快速实时应用
tts-1-hd较慢制作音频
gpt-4o-audio-preview最高可变高级语音控制
gpt-4o-mini-audio-preview快速平衡的质量/速度

Gemini 模型

模型状态注意事项
gemini-2.5-flash-preview-tts实验版可能需要 Live API 才能获得完整功能

错误处理

typescript
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 适配器使用与其他适配器相同的环境变量

  • OpenAIOPENAI_API_KEY
  • GeminiGOOGLE_API_KEYGEMINI_API_KEY

显式 API 密钥

对于生产用途或需要显式控制时

typescript
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')

最佳实践

  1. 文本长度:OpenAI TTS 每请求支持最多 4096 个字符。对于更长的内容,请将其拆分为块。

  2. 语音选择:选择适合您内容的语音——使用 onyx 用于权威内容,使用 nova 用于友好互动。

  3. 格式选择:对于一般用途,使用 mp3,对于流式传输,使用 opus,对于进一步处理,使用 wav

  4. 缓存:缓存生成的音频以避免重新生成相同的内容。

  5. 错误处理:始终优雅地处理错误,尤其是在面向用户的应用程序中。