OpenRouter 上线语音转文字端点 /api/v1/audio/transcriptions

你有一段 40 分钟的电话销售录音、一个语音备忘录文件夹，或者用户正按住麦克风按钮，而你需要一份文字转录。通常的做法是，在已经处理聊天流量的系统之上，再搭建一个 Whisper 服务器，或者专门为语音转文字添加第二个提供商的 SDK。在 OpenRouter 上，你可以把音频发送到 POST /api/v1/audio/transcriptions，然后拿回包含转录文本和用量对象的 JSON，使用与 Chat Completions 相同的 API 密钥和认证。

你不需要新的 SDK 或单独的服务。因为转录与你的聊天流量运行在同一平台上，由多个提供商托管的模型会自动在它们之间进行负载均衡，而不是被固定到单一供应商。

简而言之

• 通过将 base64 编码的音频发送到 POST /api/v1/audio/transcriptions，并从响应中读取 JSON 文本和 usage 对象来进行转录。它使用与 Chat Completions 相同的 Bearer 密钥。
• Whisper 模型在这里可用：openai/whisper-1、openai/whisper-large-v3 和 openai/whisper-large-v3-turbo。也存在更新的按 token 计费的语音转文字（STT）模型。用 ?output_modalities=transcription 来发现它们，而不是默认目录。
• 当一个转录模型由多个提供商托管时，我们会自动在它们之间进行负载均衡。你在聊天中使用的按请求路由控制（order、allow_fallbacks、data_collection、sort）目前不适用于此端点；这里的 provider 块仅携带提供商特定的选项。自带密钥（BYOK）会路由到你自己的提供商密钥，仅收取平台费用。
• 真正需要围绕设计的限制是：60 秒的上游超时、不支持音频 URL（发送 base64 JSON，或 OpenAI 风格的多部分文件，最大 25 MB），以及不支持 SRT/VTT 输出。在大多数提供商（包括 OpenAI、Groq、Deepgram 和 Mistral）上，使用 response_format: "verbose_json" 可以获得单词和片段的时间戳。
• 定价根据模型按持续时间或按 token 计费，无提供商加价。usage.cost 字段返回实际的每请求成本，以便你计量支出。

如何在 OpenRouter 上转录音频？

将 base64 编码的音频发送到 POST /api/v1/audio/transcriptions，并从 JSON 响应中读取 text 字段。你像在聊天调用中一样，将 OpenRouter API 密钥作为 Bearer 令牌传递，设置一个模型，然后把音频交给它。

响应是 JSON，其中包含一个 text 字符串，保存转录文本，以及一个 usage 对象，报告音频时长（秒）、token 计数和请求的美元成本。你发出一个请求，转录文本就会在响应体中返回，因此无需轮询，也无需跟踪任务 ID。

请求体包含一个 model 和一个 input_audio 对象。在 input_audio 中，你将文件作为 base64 数据和格式字符串放入。可选地，你还可以添加语言提示、温度和 provider 块。以下是端到端的示例：

# Encode the file to base64, then POST it.
AUDIO_B64=$(base64 -i meeting.mp3 | tr -d '\n')

curl https://openrouter.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/whisper-1",
    "input_audio": { "data": "'"$AUDIO_B64"'", "format": "mp3" },
    "language": "en"
  }'

import base64
import os

import requests

with open("meeting.mp3", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode("utf-8")

api_key = os.environ["OPENROUTER_API_KEY"]

response = requests.post(
    "https://openrouter.ai/api/v1/audio/transcriptions",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "openai/whisper-1",
        "input_audio": {"data": audio_b64, "format": "mp3"},
        "language": "en",
    },
)

print(response.json()["text"])

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

const openRouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const audioB64 = readFileSync('meeting.mp3').toString('base64');

const result = await openRouter.stt.createTranscription({
  sttRequest: {
    model: 'openai/whisper-1',
    inputAudio: { data: audioB64, format: 'mp3' },
    language: 'en',
  },
});

console.log(result.text);

有哪些语音转文字模型可用？

你可以从两个模型家族中选择。像 openai/whisper-1 这样的 Whisper 类模型按持续时间（每秒音频）定价，而更新的语音转文字模型按 token 定价。哪种适合取决于你的准确度标准、语言组合和预算。

STT 模型 ID 不会出现在默认的 /api/v1/models 目录中。这是预期行为，因为转录是你筛选的一种输出模态。

curl "https://openrouter.ai/api/v1/models?output_modalities=transcription" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

这会返回语音转文字模型及其当前的每模型定价。如果你更愿意以页面形式阅读，同一列表也存在于 Speech-to-Text 集合 中，而 模型目录 则提供实时的每模型费率。

如果你想在接入之前试用某个模型，OpenRouter Playground 可以在浏览器中转录上传的文件。

逐字段的请求契约

整个流程分三步。你把文件进行 base64 编码，带上模型和格式 POST 过去，然后从响应中读取 text 和 usage。data 字段接收原始 base64 字节，而不是 data: URI，所以不要给它加 data:audio/mp3;base64, 前缀。format 字段是必填的，它告诉上游模型如何解码这些字节。

该端点也接受 OpenAI 风格的 multipart/form-data 上传（file 加 model），上限为 25 MB。如果你已经有为 OpenAI 的 /v1/audio/transcriptions 构建的客户端，可以把它的 base URL 指向 https://openrouter.ai/api/v1，无需改动即可使用。大于 25 MB 的文件走 base64 JSON 路径。

语言提示是可选的。如果你不提供，模型会自行检测语言；在短音频或嘈杂片段上设置它可以消除一些歧义。有些提供商通过 provider 接受它们自己的额外参数。例如 Groq 通过 provider.options.groq.prompt 接受 prompt 来指定预期词汇，这有助于处理模型否则会弄错的专业名词和术语。

响应及其用量统计

响应是 JSON，包含一个 text 字符串和一个 usage 对象。用量对象让你可以按请求计量花费，而不是估算。

{
  "text": "Thanks everyone for joining. Let's start with the Q3 numbers.",
  "usage": {
    "seconds": 9.2,
    "total_tokens": 113,
    "input_tokens": 83,
    "output_tokens": 30,
    "cost": 0.000508
  }
}

那个 cost 值是我们文档中的示例，不是报价；你的实际费用取决于模型和音频长度。用量对象会报告 seconds（音频时长）、token 数量以及以美元计的 cost。响应还带有一个 X-Generation-Id 头，你可以记录下来，以便之后追踪或调试某个具体请求。

何时使用转录，何时使用音频输入或文本转语音？

当你想把音频转成文本时使用 /audio/transcriptions，当你想让模型对音频进行推理时使用聊天中的音频输入。

转录端点适用于会议记录、语音指令、字幕以及通话或播客的可搜索存档。如果你想对客服通话做情感分析、就通话内容做问答，或者在一个提示中把音频与其他模态混合使用，请在 /chat/completions 上使用 input_audio 内容类型。把文本转成语音是第三个独立的端点。

关于音频分析和文本转语音，请参阅音频 API 公告。

转录的提供商路由是如何工作的？

转录使用与聊天相同的路由层。当一个模型由多个提供商托管时，我们会把你的请求分发到它们之间，按价格进行负载均衡，这样你就不会被绑定到单一供应商。转录目前没有暴露的是按请求的路由控制。你在聊天调用中会设置的 order、only、allow_fallbacks、data_collection 和 sort 字段不会应用在 /api/v1/audio/transcriptions 上。此端点上的 provider 块承载的是提供商专属选项：

{
  "model": "openai/whisper-large-v3",
  "input_audio": { "data": "<base64>", "format": "wav" },
  "provider": {
    "options": {
      "groq": { "prompt": "Expected vocabulary: OpenRouter, API, transcription" }
    }
  }
}

该请求会向 Groq 传递一个专有名词词汇提示，否则这些词会被处理得乱七八糟。这些选项按提供商 slug 作为键，只有匹配到的提供商的选项会被转发。如果你需要为某次转录固定某个特定提供商，或强制执行按请求的数据策略，这个端点目前还不支持这种控制。完整的提供商对象记录在提供商路由文档中。

OpenRouter 不会标记提供商的定价，所以目录费率就是你支付的价格，而 Zero Completion Insurance 意味着失败的转录不会被计费。如果你已有提供商协议，BYOK 让你可以通过自己的提供商密钥进行路由，并在计划相关的免费额度之后，只需支付我们 5% 的平台费，而不是按使用量计算的模型成本；当前详情请见定价页面。

有哪些需要提前考虑的限制？

有四个约束会影响你如何构建转录调用：

由于超时限制的是处理时间而不是音频长度，仅凭片段时长无法判断它是否能通过。像通宵游戏会话这样持续数小时的录音，需要分块处理；单次调用无法覆盖。

对于字幕，默认响应是文本加用量，没有时间信息。将 response_format 设为 verbose_json，你会得到片段级时间戳；如果传入 timestamp_granularities: ["word"]，还能得到词级时间戳。OpenRouter 只会向能够返回时间戳的端点发送 verbose_json 请求，包括 OpenAI、Groq、Deepgram、Mistral 和 Azure。如果某个模型的所有端点都不能返回时间戳，比如 openai/gpt-4o-transcribe，请求会以 400 失败。没有内置的 .srt/.vtt 输出，所以你需要自己根据时间戳构建字幕文件。

转录请求的费用是多少？

你按模型的目录费率支付，我们不收取加价，usage.cost 字段会告诉你每次请求的确切费用。Whisper 级模型按音频秒数收费，较新的模型按 token 收费。

费率会变化，所以我们把实时数字保留在目录中每个模型的页面上，而不是在这里写死一个。从响应中读取 usage.cost 就能知道每次请求实际花费了多少。STT 模型是付费的，所以 API 转录会消耗你的信用余额。

要开始使用，请在Playground 中确认某个模型适合你的音频，接好调用，并从第一天起读取每次请求的 usage.cost 来计量支出。

常见问题

如何使用 OpenRouter 转录音频文件？

将 base64 编码的音频发送到 POST /api/v1/audio/transcriptions，并带上 model 和 input_audio 对象（data 加 format）。响应是 JSON，包含一个 text 字符串（转录文本）和一个 usage 对象（秒数、token 和费用）。它使用与 Chat Completions 相同的 Bearer API 密钥和认证。

OpenRouter 支持 Whisper 吗？

是的，有三个 Whisper 模型可用：openai/whisper-1、openai/whisper-large-v3 和 openai/whisper-large-v3-turbo。STT 模型 ID 不在默认的 /api/v1/models 列表中，因此你需要通过 ?output_modalities=transcription 进行筛选或浏览 Speech-to-Text 来发现它们。Whisper 按音频时长计费，按每秒音频计价；较新的 STT 模型则按 token 计价。

OpenRouter 转录接受哪些音频格式？

常见格式包括 wav、mp3、flac、m4a、ogg、webm 和 aac，通过必需的 input_audio.format 字段传入。支持情况因模型而异，因此并非每个模型都支持所有格式。wav 是兼容性最广、最稳妥的默认选择；像 mp3 这样的压缩格式则能提供更小、更快的负载。

OpenRouter 能返回时间戳或 SRT/VTT 字幕吗？

时间戳可以。将 response_format 设为 verbose_json 可获得片段级时间戳，再加上 timestamp_granularities: ["word"] 可在 words 数组中获取词级时间戳。大多数提供商都支持，包括 OpenAI、Groq、Deepgram、Mistral 和 Azure；如果某个模型没有能返回时间戳的端点，例如 openai/gpt-4o-transcribe，则会以 400 拒绝该请求。不支持 SRT/VTT 输出，因此你需要自行根据时间戳构建字幕文件。

音频可以有多长？

实际限制是上游约 60 秒的处理超时，而不是固定的音频长度上限。短片段和中等长度的片段可一次调用返回。对于长录音，请将音频切分为多个片段，分别转录，再将文本拼接起来。

OpenRouter 上的转录费用是多少？

你按模型目录价格付费，没有加价。Whisper 类模型按音频秒数计价；较新的 STT 模型按 token 计价。每个响应中的 usage.cost 字段会报告该请求的确切美元费用。