OpenRouter 入门与概览

OpenRouter 入门与概览

文本转语音

5 分钟阅读

文字转语音（TTS）

如何使用 OpenRouter 模型将文本合成为语音音频

OpenRouter 通过专用的 /api/v1/audio/speech 端点支持文字转语音（TTS），该端点兼容 OpenAI Audio Speech API。发送文本后，会以你选择的格式收到原始音频字节流。

查找模型

你可以通过多种方式查找 TTS 模型：

通过 API

在 Models API 上使用 output_modalities 查询参数来发现 TTS 模型：

# 仅列出 TTS 模型
curl "https://openrouter.ai/api/v1/models?output_modalities=speech"

在模型页面上

访问模型页面，按输出模态筛选，查找具备语音合成能力的模型。请查找在输出模态中列出 "speech" 的模型。

API 用法

向 /api/v1/audio/speech 发送 POST 请求，并附上要合成的文本。响应是原始音频字节流（不是 JSON），因此可以直接写入文件或交给音频播放器。

基础示例

import { OpenRouter } from '@openrouter/sdk';
import fs from 'fs';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const stream = await openRouter.tts.createSpeech({
  model: 'openai/gpt-4o-mini-tts-2025-12-15',
  input: '你好！这是一次文字转语音测试。',
  voice: 'alloy',
  responseFormat: 'mp3',
});

// 收集音频流并保存到文件
const reader = stream.getReader();
const chunks: Uint8Array[] = [];
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}
const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
const buffer = new Uint8Array(totalLength);
let offset = 0;
for (const chunk of chunks) {
  buffer.set(chunk, offset);
  offset += chunk.length;
}
await fs.promises.writeFile('output.mp3', buffer);
console.log('音频已保存到 output.mp3');

请求参数

参数类型是否必需说明
modelstring是要使用的 TTS 模型（例如 openai/gpt-4o-mini-tts-2025-12-15、mistralai/voxtral-mini-tts-2603）
inputstring是要合成为语音的文本
voicestring取决于服务提供商语音标识符。可用语音因模型而异，请在模型页面上查看各模型支持的语音。仅当所选模型服务提供商文档中说明有默认语音时，才可省略此参数；否则必须显式指定语音。
response_formatstring否音频输出格式：mp3 或 pcm。默认为 pcm
speednumber否播放速度倍率。仅由支持该参数的模型使用（例如 OpenAI TTS）。其他模型服务提供商会忽略。默认为 1.0
input_referencesarray否用于无状态语音克隆的参考内容：一个承载语音样本的 input_audio 部分，可选再附带一个包含其转写文本的 text 部分。参见下文语音克隆
providerobject否模型服务提供商特定的透传配置

省略 voice 时，OpenRouter 只会把请求转发给其适配器支持服务提供商侧默认语音的模型服务提供商。对于其他模型服务提供商，请求会因校验错误被拒绝。

语音克隆

部分模型支持无状态语音克隆：你在 TTS 请求中直接发送一小段参考音频，生成的语音会模仿该声音。无需单独的语音创建或上传步骤。

将参考音频作为 Base64 的 input_audio 部分放入 input_references（data:audio/...;base64, URI 也可以），并可选择将其转写文本作为 text 部分一并提供：

{
  "model": "fish-audio/s2.1-pro",
  "input": "你好，这是用我克隆的声音说的！",
  "response_format": "mp3",
  "input_references": [
    { "type": "input_audio", "input_audio": { "data": "data:audio/wav;base64,UklGRuQXDAB..." } },
    { "type": "text", "text": "这是参考音频的转写文本。" }
  ]
}

注意：同一语音克隆模型的部分模型服务提供商可能不支持语音克隆。请在 endpoints API 上查看 supports_voice_cloning 字段。

限制与要求：

  • 参考样本支持的音频格式因模型服务提供商而异。
  • input_references 最多接受一个 input_audio 部分和一个 text 部分，并且必须包含 input_audio。
  • 参考音频限制为 20 MiB 的 Base64（解码后音频 15 MiB）；更大的请求会以 400 被拒绝。

模型服务提供商特定选项

你可以使用 provider 参数传入模型服务提供商特定选项。选项以模型服务提供商 slug 为键，只有匹配到的模型服务提供商的选项会被转发：

{
  "model": "openai/gpt-4o-mini-tts-2025-12-15",
  "input": "你好，世界",
  "voice": "alloy",
  "provider": {
    "options": {
      "openai": {
        "instructions": "请用温暖、友好的语气说话。"
      }
    }
  }
}

Azure（MAI-Voice-2）

Azure TTS 在内部使用语音合成标记语言（SSML），但这一层已完全抽象，你只需使用标准参数。voice 参数接受 Azure 语音名称（例如 en-US-Harper:MAI-Voice-2），并且支持 speed（范围：0.5–2.0）。

若要进行富有表现力的合成，可通过模型服务提供商选项传入 style，并可选择传入 styledegree：

{
  "model": "microsoft/mai-voice-2",
  "input": "欢迎来到本次活动！",
  "voice": "en-US-Harper:MAI-Voice-2",
  "response_format": "mp3",
  "speed": 1.0,
  "provider": {
    "options": {
      "azure": {
        "style": "cheerful",
        "styledegree": 1.2
      }
    }
  }
}
选项类型说明
stylestring富有表现力的说话风格（例如 cheerful、sad、angry、excited）。可用风格取决于所选语音。
styledegreenumber风格效果的强度。默认为 1.0；数值越高，表现力越强。

响应格式

TTS 端点返回的是原始音频字节流，而非 JSON。响应包含以下请求头：

请求头说明
Content-Type音频的 MIME 类型。mp3 格式为 audio/mpeg，pcm 格式为 audio/pcm
X-Generation-Id本次请求的唯一 generation ID，便于跟踪和调试

输出格式

格式Content-Type说明
mp3audio/mpeg压缩音频，文件更小。适合存储和播放
pcmaudio/pcm未压缩的原始音频。延迟更低，适合实时流式处理流水线

定价

TTS 模型按输入文本的字符计费。定价因模型和模型服务提供商而异。你可以在模型页面或通过 Models API 查看各模型的每字符费用。

与 OpenAI SDK 兼容

TTS 端点与 OpenAI SDK 完全兼容。你可以将 OpenAI 客户端库的地址指向 OpenRouter 的基础 URL：

from openai import OpenAI

client = OpenAI(
  base_url="https://openrouter.ai/api/v1",
  api_key="<OPENROUTER_API_KEY>",
)

# 非流式：获取完整音频响应
response = client.audio.speech.create(
  model="openai/gpt-4o-mini-tts-2025-12-15",
  input="那只敏捷的棕色狐狸跳过了懒惰的狗。",
  voice="nova",
  response_format="mp3"
)
response.write_to_file("output.mp3")

# 流式：在音频分块到达时处理
with client.audio.speech.with_streaming_response.create(
  model="openai/gpt-4o-mini-tts-2025-12-15",
  input="那只敏捷的棕色狐狸跳过了懒惰的狗。",
  voice="nova",
  response_format="mp3"
) as response:
  response.stream_to_file("output.mp3")

最佳实践

  • 选择合适的格式：存储和常规播放使用 mp3。在延迟敏感的实时流式处理流水线中使用 pcm
  • 选择语音：不同模型服务提供商提供不同语音。请查阅模型文档，或试用可用语音，找到最适合你场景的选择
  • 输入长度：对于很长的文本，考虑将输入拆成较小片段，再拼接音频输出。这可以提高可靠性，并降低首个音频分块的延迟
  • speed 参数：speed 参数仅由部分模型服务提供商支持（例如 OpenAI）。不支持该参数的模型服务提供商会静默忽略它

故障排除

音频文件为空或已损坏？

  • 确认 response_format 与保存文件的方式一致（例如，不要把 pcm 输出保存为 .mp3 扩展名）
  • 检查响应状态码，因为非 200 响应返回的是 JSON 错误体，而非音频

找不到模型？

  • 使用模型页面查找可用的 TTS 模型
  • 确认模型 slug 正确（例如 openai/gpt-4o-mini-tts-2025-12-15，而不是 gpt-4o-mini-tts）

语音不可用？

  • 可用语音因模型服务提供商而异。请查阅该模型服务提供商的文档，了解支持的语音标识符
  • 每个模型都有自己的语音集合，请在模型页面上查看该模型页面以获取完整列表
上一页视频生成下一页 语音转文本