我们通过兼容 OpenAI 的 POST /api/v1/audio/speech 端点支持文本转语音（TTS）。发送文本、模型和受支持的语音，然后保存或流式传输音频。使用一个 API 密钥即可通过相同的请求结构访问来自多个提供商的 TTS 模型。
本教程涵盖身份验证、合成、响应验证、流式传输以及模型或语音的更改。
简而言之
将 TTS 请求发送至 https://openrouter.ai/api/v1/audio/speech 。
使用 OpenAI Python SDK，将 base_url 设置为 https://openrouter.ai/api/v1 。
当模型支持其他语音时，只需在一行代码中更改 voice 值。在切换提供商时，请同时更改匹配的模型和语音。
您在请求正文中指定模型名称。无论您选择哪个提供商的语音模型，端点、身份验证和响应处理都保持不变。
我们的音频 API 公告涵盖了更广泛的发布内容。对于语音转文本，请使用我们的转录指南 。
使用 OpenRouter 文本转语音所需的内容
创建一个 OpenRouter API 密钥并将其存储在环境变量中，以使其远离源代码。
在 macOS 或 Linux 上，为当前终端会话设置变量：
export OPENROUTER_API_KEY = "your-api-key"
所有示例均使用 https://openrouter.ai/api/v1 作为基础 URL，并在 Authorization: Bearer 头中发送密钥。
该端点接受两个必填字段以及大多数模型所需的语音字段：
model 用于选择语音模型。
input 包含您希望模型朗读的文本。
voice 用于选择该模型支持的语音。仅当提供商文档说明存在默认语音时，才可以省略此字段，因此在实践中应将其视为必填项。
response_format 和 speed 是可选的，但显式设置输出格式可使响应更具可预测性，因为格式支持因模型而异。当您省略 response_format 时，我们的端点默认为 PCM，而 Mistral Voxtral Mini TTS 仅接受 MP3，且 speed 仅在支持的模型上改变语速。
成功的请求将返回原始音频字节，而非成功的请求将返回 JSON。在将其写入音频文件之前，请验证响应。
明确了密钥和响应行为后，您就可以生成第一个音频文件了。
使用 cURL 生成第一个 MP3 文件
以下请求使用 Mistral Voxtral Mini TTS 及其 en_paul_neutral 语音。它将返回的字节直接保存到 output.mp3 。
curl --silent \
--show-error \
--fail-with-body \
--request POST \
--url https://openrouter.ai/api/v1/audio/speech \
--header "Authorization: Bearer $OPENROUTER_API_KEY " \
--header "Content-Type: application/json" \
--data '{
"model": "mistralai/voxtral-mini-tts-2603",
"input": "OpenRouter turns this text into speech through one API endpoint.",
"voice": "en_paul_neutral",
"response_format": "mp3"
}' \
--dump-header output.headers \
--output output.mp3
这些标志有助于正确处理失败的请求。--fail-with-body 使 cURL 在收到 4xx 或 5xx 响应时以错误退出，并且由于设置了 --output，它会将服务器的 JSON 错误正文写入 output.mp3 而不是终端。当命令失败时，使用 cat output.mp3 读取错误，并在重试之前删除该文件，以免将 JSON 文件作为音频播放。--dump-header 保存响应头，以便您可以确认内容类型并捕获生成 ID。
在播放音频之前，请确认 output.mp3 存在且包含数据：
ls -lh output.mp3
在 macOS 上，您可以使用 afplay output.mp3 播放它。在 Linux 上，请使用已安装的播放器（如 ffplay ）。
当将此请求移入应用程序代码时，请确认请求成功且响应包含音频后再保存它。这些检查可防止将 JSON 错误响应写入 MP3 文件。
使用 Python 生成并保存语音
如果您的项目尚未使用 requests，请安装它：
python -m pip install requests
此示例检查 HTTP 状态码，并在保存文件之前验证我们返回的是 MP3 数据：
import os
from pathlib import Path
import requests
response = requests.post(
"https://openrouter.ai/api/v1/audio/speech" ,
headers = {
"Authorization" : f "Bearer { os.environ[ 'OPENROUTER_API_KEY' ] } " ,
"Content-Type" : "application/json" ,
},
json = {
"model" : "mistralai/voxtral-mini-tts-2603" ,
"input" : (
"OpenRouter turns this text into speech through one API endpoint."
),
"voice" : "en_paul_neutral" ,
"response_format" : "mp3" ,
},
timeout = 60 ,
)
response.raise_for_status()
content_type = response.headers.get( "Content-Type" , "" ).split( ";" )[ 0 ]
if content_type != "audio/mpeg" :
raise RuntimeError ( f "Expected audio/mpeg, received { content_type } " )
Path( "output.mp3" ).write_bytes(response.content)
generation_id = response.headers.get( "X-Generation-Id" )
print ( f "Saved output.mp3. Generation ID: { generation_id } " )
raise_for_status() 会在 API 返回 4xx 或 5xx 响应时引发异常，从而防止应用程序将错误主体保存为音频。如果请求成功，内容类型检查会确认响应包含音频后再将其写入文件。记录 X-Generation-Id 以便您可以追踪该请求或在联系支持服务时提供参考。
当 SDK 管理响应流时，同样的验证同样适用。下一个示例保留了 OpenRouter 的基础 URL，并将文件处理移至 OpenAI Python 客户端。
使用 OpenAI Python SDK 流式传输响应
我们的 TTS 端点遵循 OpenAI Audio Speech API 的结构。您可以将 OpenAI 客户端指向我们的基础 URL，并将 HTTP 响应流式传输到文件中：
import os
from pathlib import Path
from openai import OpenAI
client = OpenAI(
api_key = os.environ[ "OPENROUTER_API_KEY" ],
base_url = "https://openrouter.ai/api/v1" ,
)
with client.audio.speech.with_streaming_response.create(
model = "mistralai/voxtral-mini-tts-2603" ,
voice = "en_paul_neutral" ,
input = "OpenRouter can stream this response into an audio file." ,
response_format = "mp3" ,
) as response:
response.stream_to_file(Path( "output.mp3" ))
这种模式在保存文件的同时增量读取响应。渐进式播放需要一个能够缓冲传入数据块的播放器。
JavaScript 可以通过 arrayBuffer() 读取相同的响应。此示例在创建文件之前检查状态和内容类型：
import { writeFile } from "node:fs/promises" ;
const response = await fetch (
"https://openrouter.ai/api/v1/audio/speech" ,
{
method: "POST" ,
headers: {
Authorization: Bearer ${ process . env . OPENROUTER_API_KEY } ,
"Content-Type" : "application/json" ,
},
body: JSON . stringify ({
model: "mistralai/voxtral-mini-tts-2603" ,
input: "OpenRouter returns audio bytes to JavaScript." ,
voice: "en_paul_neutral" ,
response_format: "mp3" ,
}),
},
);
if ( ! response.ok) {
throw new Error ( HTTP ${ response . status }: ${ await response . text () } );
}
const contentType = response.headers. get ( "content-type" )?. split ( ";" )[ 0 ];
if (contentType !== "audio/mpeg" ) {
await response.body?. cancel ();
throw new Error ( Expected audio/mpeg, received ${ contentType } );
}
await writeFile ( "output.mp3" , Buffer. from ( await response. arrayBuffer ()));
console. log (response.headers. get ( "x-generation-id" ));
当您需要一个体积更小且能与标准音频播放器兼容的文件时，请选择 MP3。PCM 可避免压缩开销，并能在兼容的实时流式传输管道中降低延迟。我们返回 audio/mpeg 格式的 MP3 和 audio/pcm 格式的 PCM，可选地包含 rate 和 channels 参数，尽管可用的格式取决于所选模型。Mistral Voxtral Mini TTS 仅接受 MP3，因此请求 PCM 会返回 400 错误。播放原始 PCM 还需要正确的音频设置，因为将文件扩展名更改为 .mp3 并不会转换音频格式。
传输代码在支持的模型之间保持不变。model 和 voice 字段必须保持为有效配对。
更改 TTS 模型和声音
语音标识符属于特定模型。在同一模型内进行语音比较时，可以仅更改一行。例如，当前的 Grok Voice TTS 1.0 模型页面列出了五个内置语音：eve、ara、rex、sal 和 leo。
从以下模型和语音配对开始：
"model" : "x-ai/grok-voice-tts-1.0" ,
"voice" : "eve"
然后仅更改语音行：
Grok 示例还展示了从 Mistral 到 xAI 的提供商变更。同时更新模型和语音，因为每个提供商都提供其自己的模型和语音 ID，而端点、身份验证、输入和响应检查保持不变：
在发送请求之前，请在所选模型页面上确认这两个值，因为模型的可用性和语音目录可能会发生变化。
使用 Models API 检索当前的 TTS 模型：
curl "https://openrouter.ai/api/v1/models?output_modalities=speech"
您也可以浏览我们的文本转语音模型集合。
模型 ID | 示例语音 | 显著选项
mistralai/voxtral-mini-tts-2603 | en_paul_neutral | 通过 OpenRouter 语音端点输出 MP3
x-ai/grok-voice-tts-1.0 | eve、ara、rex、sal、leo | 跨 20 多种语言的五个内置语音
microsoft/mai-voice-2 | en-US-Harper:MAI-Voice-2 | speed、Azure style 和 styledegree
我们的 TTS 文档描述了您可以针对支持这些功能的模型通过 provider.options.
Microsoft MAI-Voice-2 接受 Azure 语音名称。它还支持记录的 0.5 到 2.0 的速度范围以及表达性的 Azure 选项：
{
"model" : "microsoft/mai-voice-2" ,
"input" : "Welcome to the product update." ,
"voice" : "en-US-Harper:MAI-Voice-2" ,
"response_format" : "mp3" ,
"speed" : 1.0 ,
"provider" : {
"options" : {
"azure" : {
"style" : "cheerful" ,
"styledegree" : 1.2
}
}
}
}
这些控制措施仍然特定于提供商。不受支持的提供商可能会忽略 speed，而样式取决于所选的语音。请将提供商选项与匹配的模型配置放在一起。
模型和语音的选择决定了哪些格式和表达性控制可用。生产路径必须在每次生成记录中保留这些设置。
为生产准备集成
在句子或段落边界处拆分长输入，按顺序请求每个片段，并使用了解格式的工具备份音频。这提高了可靠性并更早返回第一个片段。
对每个片段应用相同的响应检查：
遇到非成功 HTTP 状态码时停止。
确认 Content-Type 与请求的格式匹配。
拒绝空响应。
使用模型、语音、格式和应用请求 ID 记录 X-Generation-Id。
在重试之前对响应进行分类，以便永久性请求失败不会进入退避循环。
重试 429、502、503、524 和 529 响应，因为速率限制、提供商错误、暂时不可用、超时和提供商过载可能在后续尝试中清除。如果响应包含 Retry-After 标头，请遵循该标头。否则，使用有上限的指数退避，并在少量尝试后停止。在更正请求、凭据或可用积分之前，不要重试 400、401 或 402 响应。
TTS 模型按输入文本的字符数定价。定价因模型和提供商而异，因此在估算生产成本之前，请检查当前模型页面或 Models API。
这些控制措施涵盖了可靠性、可追溯性和成本。其余故障通常源于将错误正文保存为音频，或将模型与不受支持的语音或格式结合使用。
排查常见的 OpenRouter TTS 错误
为什么 MP3 中包含 JSON？
API 返回了错误，且程序在未检查状态码的情况下保存了其主体内容。请在写入响应之前调用 raise_for_status() 或检查状态码。
为什么音频文件为空或已损坏？
空文件或无法读取的文件通常意味着请求未返回任何音频数据，或者响应以错误的格式被保存。请在保存之前检查响应大小和 Content-Type。将 audio/mpeg 保存为 MP3 格式，并将 audio/pcm 作为原始 PCM 处理，同时使用正确的播放器设置，因为仅更改扩展名为 .mp3 并不会转换音频编码。
为什么 OpenRouter 拒绝该声音？
声音标识符因模型而异。请检查所选模型的页面，并发送其支持的声音之一。每次更换模型时，都请重新确认声音。
为什么某个提供商选项没有效果？
提供商控制仅对匹配的提供商生效。请将 OpenAI 指令置于 provider.options.openai 下，将 Azure 风格的控制置于 provider.options.azure 下。部分提供商会静默忽略不支持的速度值。
在涵盖响应检查和特定于提供商的设置后，剩余的问题主要集中在端点、OpenAI SDK 兼容性以及查找当前 TTS 模型上。
常见问题解答
OpenRouter 是否提供文本转语音功能？
是的。向 https://openrouter.ai/api/v1/audio/speech 发送 POST 请求，包含模型、文本输入以及该模型支持的声音。我们将返回所选模型支持的原始音频字节。
OpenRouter TTS 是否与 OpenAI SDK 兼容？
是的。将 SDK 的基础 URL 设置为 https://openrouter.ai/api/v1 并使用您的 OpenRouter API 密钥。模型 ID、声音 ID 和特定于提供商的控制必须与您选择的模型相匹配。
我如何使用文本转语音 API？
向 https://openrouter.ai/api/v1/audio/speech 发送经过身份验证的 POST 请求，包含 model、input 和 voice。设置受支持的 response_format，检查 HTTP 状态码和内容类型，然后将返回的音频字节写入文件或传递给兼容的播放器。
OpenAI API 中的 TTS 是什么？
文本转语音通过 Audio Speech API 将文本输入转换为生成的音频。我们使用相同的请求结构，因此 OpenAI SDK 客户端在更改基础 URL 并提供 OpenRouter API 密钥后，可以调用受支持的 OpenRouter TTS 模型。
我如何查找当前的 OpenRouter TTS 模型？
请求 GET /api/v1/models?output_modalities=speech 或浏览文本转语音合集。使用模型页面确认支持的声音和当前定价。
这些工作流中的端点、身份验证和响应检查保持一致。特定于模型的语音、格式和控制是您在进行每次集成或比较前需要确认的值。
通过 OpenRouter 生成语音
在已配置好端点、模型、声音以及响应检查的情况下，您可以通过 cURL、Python、JavaScript 或 OpenAI SDK 生成可播放的音频文件。请求结构在 TTS 模型之间保持一致，而每个模型则决定可用的声音、格式和提供商控制。
准备好生成第一个文件时，请创建 API 密钥。在比较模型或为生产环境准备集成时，请浏览我们的文本转语音模型合集和 TTS 参考文档。