你有一段40分钟的销售通话录音、一个文件夹的语音备忘录，或者有用户一直按着麦克风按钮，而你需要一份文字转录稿。通常的做法是搭建一个Whisper服务器，或者在你已有的聊天流量处理方案之上，再额外接入一个仅用于语音转文本的第三方提供商SDK。在OpenRouter上，你可以将音频发送到 `POST /api/v1/audio/transcriptions` 接口，然后获得包含转录文本和用量对象的JSON响应，使用的API密钥和认证方式与Chat Completions相同。

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

摘要

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

如何在OpenRouter上转录音频？

将 base64 编码的音频发送至 `POST /api/v1/audio/transcriptions`，然后从 JSON 响应中读取 `text` 字段。您需要像在聊天调用中一样，将 OpenRouter API 密钥作为 Bearer token 传递，设置一个模型，然后将音频数据交给它。

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

请求体包含一个 `model` 字段和一个 `input_audio` 对象。在 `input_audio` 内部，您需要将文件作为 base64 数据和一个 `format` 字符串放入。您还可以选择性地添加语言提示（`language`）、温度参数（`temperature`）和一个 `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"

这会返回语音转文本模型及其当前的按模型定价。如果您更愿意以页面形式阅读，相同的列表也存在于 [此处]；模型目录中则包含实时的按模型费率。

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

逐字段的请求规范

整个流程分为三步。您将文件进行 base64 编码，将其与模型和格式一起通过 POST 提交，然后从响应中读取 `text` 和 `usage` 字段。`data` 字段接受原始的 base64 字节，而不是 `data:` URI，因此请不要为其添加 `data:audio/mp3;base64,` 前缀。`format` 字段是必需的，它告诉上游模型如何解码这些字节。

参数	是否必需	说明
model	是	语音转文本（STT）模型标识符，例如 `openai/whisper-1`
input_audio.data	是	音频的 base64 编码（原始字节，非 `data:` URI）
input_audio.format	是	可选值之一：`wav`、`mp3`、`flac`、`m4a`、`ogg`、`webm`、`aac`
language	否	ISO-639-1 语言代码（如 `en`、`es` 等）。如果省略，将自动检测
temperature	否	采样温度，取值范围 0 到 1
response_format	否	json（默认）或 verbose_json，后者会额外返回任务、语言、时长和片段时间戳（仅限兼容 OpenAI 的提供商）
timestamp_granularities	否	使用 verbose_json 时可选 ["segment"] 或 ["word"]；选择 word 会在 words 数组中添加词级别的时间戳
provider	否	提供商特定参数的透传（例如 Groq 的 prompt）。该端点不应用按请求的路由控制

该端点也接受 OpenAI 风格的 multipart/form-data 上传（文件加模型），大小限制为 25 MB。如果你已有面向 OpenAI 的 `/v1/audio/transcriptions` 构建的客户端，只需将 base URL 指向 `https://openrouter.ai/api/v1` 即可直接使用，无需修改。超过 25 MB 的文件则通过 base64 JSON 路径处理。

语言提示为可选参数。如果省略，模型会自动检测语言；设置该参数可以消除短音频或嘈杂音频中的部分歧义。部分提供商通过 provider 字段接受自己的额外参数。例如，Groq 可通过 `provider.options.groq.prompt` 传入预期词汇的提示词，这有助于模型正确处理专有名词和术语，避免出错。

响应及其用量统计

响应为 JSON 格式，包含一个 text 字符串和一个 usage 对象。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
  }
}

该费用值来自我们文档中的示例，并非实际报价；你的实际费用取决于所选模型和音频时长。usage 对象会报告秒数（音频时长）、token 数量以及以美元计的费用。响应中还包含一个 `X-Generation-Id` 标头，你可以记录该 ID 以便后续追踪或调试特定请求。

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

当你需要将音频转换为文本时，使用 `/audio/transcriptions`；当你希望模型对音频内容进行推理时，则在聊天中使用音频输入。

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

你想要…	使用	你将获得
音频转文本（转录稿）	POST /api/v1/audio/transcriptions	JSON 文本加用量
一个能对音频进行推理（情感分析、问答、多模态）的模型	/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）为键，只有匹配到的提供商的选项才会被转发。如果你需要固定使用某个特定提供商，或在转写请求上强制执行按请求的数据策略，该端点目前尚不支持这些控制。完整的 provider 对象在提供商路由文档中有详细说明。

OpenRouter 不会在提供商定价上加价，因此目录价格就是你的实际支付价格，而“零补全保险”意味着失败的转写不会被计费。如果你已有提供商协议，BYOK 功能允许你通过自己的提供商密钥进行路由，只需支付我们的平台费用，而无需支付按使用量计算的模型成本，并且按量付费模式下，每月前 100 万次请求的平台费用将被免除。

规划时需要考虑哪些限制？

有四个约束条件决定了你如何构建转写调用：

限制	对你的影响
60 秒上游超时	约 60 秒的处理时间，并非音频长度的硬性上限。体积大或未压缩的录音容易超时。请将长音频分割成片段，分别转写，再拼接文本。
不支持音频 URL	该端点不支持通过 URL 传递音频。请发送 base64 JSON，或采用 OpenAI 风格的多部分文件，大小不超过 25 MB。压缩格式（mp3、aac）能生成更小、传输更快的负载。
不支持 SRT/VTT 格式输出	srt、vtt 和 text 响应格式会被拒绝并返回 400 错误。时间戳可通过兼容 OpenAI 的提供商上的 verbose_json 获取；请自行根据这些时间戳构建字幕文件。
格式支持因提供商而异	列表（wav/mp3/flac/m4a/ogg/webm/aac）是常见的，但特定模型或提供商可能不接受其中所有格式。wav 是最安全的默认选择。

由于超时限制的是处理时间而非音频长度，因此仅凭片段时长无法判断其是否可行。一段持续数小时的录音，例如通宵游戏会话，需要进行分块处理；单次调用无法覆盖。

对于字幕，默认响应是文本加使用情况，不包含时间信息。将 response_format 设置为 verbose_json，即可获得片段级别的时间戳，如果同时传入 timestamp_granularities: ["word"]，还能获得单词级别的时间戳。这在兼容 OpenAI 的提供商（OpenAI、Groq、Together）上有效；其他提供商会拒绝并返回 400 错误。没有内置的 .srt/.vtt 输出，因此您需要自行根据时间戳构建字幕文件。

转录请求的费用是多少？

您按模型的目录费率付费，我们不加价，并且 usage.cost 字段会显示每次请求的确切费用。Whisper 类模型按音频秒数收费，较新的模型则按 token 收费。

费率会变化，因此我们将实时费率保留在目录中每个模型的页面上，而不是在此处列出。读取响应中的 usage.cost 可以告诉您每次请求的实际成本。STT 模型是付费的，因此 API 转录会消耗您的信用余额。

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

常见问题

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

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

OpenRouter 支持 Whisper 吗？

是的。Whisper 类模型可用于转录，使用的 slug 是 openai/whisper-1。STT 模型 ID 不在默认的 /api/v1/models 列表中，因此需要通过 `?output_modalities=transcription` 进行筛选，或浏览相关页面来发现它们。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 的提供商（OpenAI、Groq、Together）；其他提供商会返回 400 错误拒绝该请求。不支持 SRT/VTT 输出，因此需要自行根据时间戳构建字幕文件。

音频时长可以有多长？

实际限制是上游约 60 秒的处理超时时间，而非固定的音频长度上限。短片段和中长片段可通过一次调用完成。对于长录音，需将音频分割成多个片段，分别转录后再拼接文本。

在 OpenRouter 上转录的费用是多少？

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