OpenRouter 入门与概览

OpenRouter 入门与概览

语音转文本

5 分钟阅读

语音转文字（STT）

如何使用 OpenRouter 模型将音频转写为文本

OpenRouter 通过专用的 /api/v1/audio/transcriptions 端点支持语音转文字（STT）。发送 Base64 编码的音频，即可收到包含转写文本和用量统计的 JSON 响应。

查找模型

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

通过 API

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

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

在模型页面上

访问模型页面，按输出模态筛选，查找具备音频转写能力的模型。你也可以浏览语音转文字精选集合以查看整理后的列表。

API 用法

向 /api/v1/audio/transcriptions 发送包含 Base64 编码音频的 JSON 请求体。响应为 JSON，包含转写文本以及可选的用量统计。

基础示例

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

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

const audioBuffer = await fs.promises.readFile('audio.wav');
const base64Audio = audioBuffer.toString('base64');

const result = await openRouter.stt.createTranscription({
  model: 'openai/whisper-1',
  inputAudio: {
    data: base64Audio,
    format: 'wav',
  },
});

console.log(result.text);

请求参数

参数类型是否必需说明
modelstring是要使用的 STT 模型（例如 openai/whisper-1）
input_audioobject是要转写的音频数据
input_audio.datastring是Base64 编码的音频数据（原始字节，不是 Data URI）
input_audio.formatstring是音频格式（例如 wav、mp3、flac、m4a、ogg、webm、aac）
languagestring否ISO-639-1 语言代码（例如 "en"、"ja"）。若省略则自动检测
temperaturenumber否介于 0 和 1 之间的采样温度。数值越低，结果越确定
providerobject否模型服务提供商特定的透传配置

兼容 OpenAI 的 multipart 请求

该端点也接受 OpenAI 风格的 multipart/form-data 请求，因此面向 OpenAI /v1/audio/transcriptions 构建的客户端（包括官方 OpenAI SDK）只需将基础 URL 指向 https://openrouter.ai/api/v1 即可使用：

OpenAI SDK (Python)
from openai import OpenAI

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

with open("audio.wav", "rb") as f:
    result = client.audio.transcriptions.create(
        model="openai/whisper-large-v3",
        file=f,
    )

print(result.text)
cURL (multipart)
curl https://openrouter.ai/api/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F file="@audio.wav" \
  -F model="openai/whisper-large-v3"

支持 file、model、language、temperature、response_format 和 timestamp_granularities 字段。prompt 会被接受但忽略。response_format 可以是 json（默认）或 verbose_json；后者会在响应中加入 task、language、duration 以及片段级时间戳。verbose_json 仅在兼容 OpenAI 的模型服务提供商上可用（OpenAI、Groq、Together）。其他模型服务提供商会以 400 拒绝该格式。text、srt 和 vtt 会以 400 拒绝。使用 verbose_json 时，传入 timestamp_granularities[]=word 还可在 words 数组中收到词级时间戳（segment 是模型服务提供商的默认值）。同样的 response_format 和 timestamp_granularities 字段也适用于 Base64 JSON 路径。

multipart 上传限制为 25 MB，与 OpenAI 的上限相同。对于压缩格式，这足以覆盖较长录音：大约 26 分钟的 128 kbps MP3、52 分钟的 64 kbps，或超过 2 小时的 24 kbps Opus 语音备忘。未压缩的 WAV 会更快达到上限（16 kHz 单声道大约 13 分钟）；长录音建议使用 mp3 或 opus。更大的文件应以 Base64 JSON 通过 input_audio 发送，该方式支持流式卸载。处理时间大约超过一分钟的录音无论如何都应拆分，因为上游模型服务提供商会在每个请求 60 秒后超时。

模型服务提供商特定选项

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

{
  "model": "openai/whisper-large-v3",
  "input_audio": {
    "data": "UklGRiQA...",
    "format": "wav"
  },
  "provider": {
    "options": {
      "groq": {
        "prompt": "预期词汇：OpenRouter、API、转写"
      }
    }
  }
}

响应格式

STT 端点返回包含转写文本的 JSON 响应：

{
  "text": "Hello, this is a test of speech-to-text transcription.",
  "usage": {
    "seconds": 9.2,
    "total_tokens": 113,
    "input_tokens": 83,
    "output_tokens": 30,
    "cost": 0.000508
  }
}

响应字段

字段类型说明
textstring转写文本
usage.secondsnumber输入音频的时长（秒）
usage.total_tokensnumber使用的 Token 总数（输入 + 输出）
usage.input_tokensnumber计费的输入 Token 数
usage.output_tokensnumber生成的输出 Token 数
usage.costnumber本次请求的总费用（美元）

响应头

请求头说明
X-Generation-Id本次请求的唯一 generation ID，便于跟踪和调试

支持的音频格式

支持的音频格式因模型服务提供商而异。常见格式包括：

格式MIME 类型说明
wavaudio/wav未压缩音频，质量最高
mp3audio/mpeg压缩音频，兼容性广泛
flacaudio/flac无损压缩音频
m4aaudio/mp4MPEG-4 音频
oggaudio/oggOgg Vorbis 音频
webmaudio/webmWebM 音频，常见于浏览器录音
aacaudio/aac高级音频编码

定价

STT 模型的计费策略因模型服务提供商而异：

  • 按时长计费（例如 OpenAI Whisper）：按输入音频的秒数计费
  • 按 Token 计费（例如较新的 OpenAI 模型）：按输入/输出 Token 计费，与文本模型类似

你可以在模型页面或通过 Models API 查看各模型的费用。响应中的 usage.cost 字段显示每次请求的实际费用。

BYOK（Bring Your Own Key，自带密钥）

STT 支持 BYOK，允许你使用自己的模型服务提供商 API 密钥。配置后，请求会使用你的密钥直接路由到该模型服务提供商，OpenRouter 只收取平台费用，而不收取按用量计算的模型费用。

演练场

你可以在浏览器中通过 OpenRouter 演练场（Playground） 直接测试 STT 模型。打开任意 STT 模型的页面，使用演练场标签页上传音频文件并查看转写结果。

与音频输入的区别

OpenRouter 支持两种处理音频的方式：

  1. 语音转文字（本页）：专用的 /api/v1/audio/transcriptions 端点，针对转写优化。返回包含转写文本和用量数据的结构化 JSON。最适合将音频转换为文本。

  2. 通过对话补全（Chat Completions）进行音频输入（音频文档）：在 /api/v1/chat/completions 请求中使用 input_audio 内容类型发送音频。模型会将音频与文本一并处理，并以对话方式回复。最适合音频分析、针对音频内容的问答，或将音频与其他模态结合。

最佳实践

  • 选择合适的格式：WAV 能为转写提供最佳质量。MP3 和其他压缩格式效果也很好，但对于临界音频可能会略微降低准确率
  • 文件大小：对于很长的音频文件，考虑拆成较小片段。上游模型服务提供商超时时间为 60 秒，过大的文件可能会超时
  • Base64 编码：音频必须以 Base64 编码数据发送（原始字节，不是 Data URI）。大多数编程语言都有内置的 Base64 编码工具

故障排除

转写结果为空或不正确？

  • 确认音频格式与请求中的 format 字段一致
  • 确保音频质量足以进行转写

请求超时？

  • 较大的音频文件可能超过 60 秒超时。将长录音拆成较小片段
  • 压缩格式（MP3、AAC）产生的载荷更小，传输也更快

找不到模型？

  • 使用模型页面或带有 output_modalities=transcription 的 Models API 查找可用的 STT 模型
  • 确认模型 slug 正确（例如 openai/whisper-1，而不是 whisper-1）

身份验证错误？

  • 确认你使用的是你的 OpenRouter 控制台中的有效 API 密钥
  • STT 端点使用与对话补全 API 相同的身份验证方式
上一页文本转语音下一页 音频