# Whisper-1 音频转录
> 支持 99 种语言的语音识别
> 多种输出格式：json / text / srt / verbose_json / vtt
> 最大文件 25MB
`POST /v1/audio/transcriptions`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
> **Note:** 
> 本接口需要上传文件，不支持在浏览器里直接「试一试」。请用 cURL、Postman 或 SDK 测试。
## 请求参数
请求体为 `multipart/form-data`。
- `file` (file / 必填) — 待转录的音频文件。 支持的格式：mp3、mp4、mpeg、mpga、m4a、wav、webm。单文件最大 25MB。
- `model` (string / 必填) — 语音识别模型名称。当前取值 `whisper-1`。
- `language` (string / 可选) — 音频语言代码，ISO-639-1 格式。明确指定可提升准确率与速度，共支持 99 种语言。 常用值：`zh` 中文、`en` 英文、`ja` 日文、`ko` 韩文。
- `prompt` (string / 可选) — 可选文本提示，用于引导转录风格或承接上一段音频内容。上限 224 token。
- `response_format` (string / 可选) — 输出格式，默认 `json`。 - `json` JSON，仅含文本 - `text` 纯文本 - `srt` SRT 字幕 - `verbose_json` 详细 JSON，含时间戳及其他元数据 - `vtt` WebVTT 字幕
- `temperature` (number / 可选) — 采样温度，取值 0 到 1，默认 0。数值越高结果越随机，越低越确定。
## 响应
- `text` (string) — 转录后的文本。所有格式下都返回该字段。
- `task` (string) — 任务类型，固定值 `transcribe`。仅 `verbose_json` 返回。
- `language` (string) — 检测到或指定的语言代码。仅 `verbose_json` 返回。
- `duration` (number) — 音频时长，单位秒。仅 `verbose_json` 返回。
- `segments` (array) — 文本片段数组。仅 `verbose_json` 返回。
### segments 元素字段
- `segments[].id` (integer) — 片段 ID。
- `segments[].start` (number) — 片段起始时间，单位秒。
- `segments[].end` (number) — 片段结束时间，单位秒。
- `segments[].text` (string) — 片段文本。
- `segments[].temperature` (number) — 该片段使用的采样温度。
- `segments[].avg_logprob` (number) — 平均对数概率。数值越接近 0 表示置信度越高。
- `segments[].compression_ratio` (number) — 压缩比。异常高的值通常提示识别出现了循环重复。
- `segments[].no_speech_prob` (number) — 无语音概率。接近 1 时说明这段大概率是静音或噪音。
## 响应示例
**json 格式：**
```json
{
  "text": "这是一段测试音频的转录文本内容。"
}
```
**verbose_json 格式：**
```json
{
  "task": "transcribe",
  "language": "zh",
  "duration": 8.5,
  "text": "这是一段测试音频的转录文本内容。",
  "segments": [
    {
      "id": 0,
      "seek": 0,
      "start": 0.0,
      "end": 3.5,
      "text": "这是一段测试音频",
      "tokens": [50364, 1234, 5678],
      "temperature": 0.0,
      "avg_logprob": -0.3,
      "compression_ratio": 1.2,
      "no_speech_prob": 0.01
    }
  ]
}
```
**srt 格式：**
```
1
00:00:00,000 --> 00:00:03,500
这是一段测试音频
2
00:00:03,500 --> 00:00:08,500
的转录文本内容。
```
## 提升准确率的做法
**指定语种。** 短音频自动识别容易判错，明确 `language` 能显著改善。
**用 prompt 喂专有名词。** 把可能出现的行业词汇、人名、缩写写进去，能减少同音错字。注意上限 224 token。
**长音频先切分。** 按静音点切成 5 到 10 分钟一段，既避开 25MB 限制，也降低单次失败的重试成本。
**用 no_speech_prob 过滤静音段。** 批量处理录音时，这个字段能帮你跳过无内容的部分。
## 错误
| HTTP | type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 请求参数无效 |
| 401 | authentication_error | 身份验证失败，请检查您的API密钥 |
| 402 | payment_required | 账户余额不足，请充值后再试 |
| 429 | rate_limit_error | 请求过于频繁，请稍后再试 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 支持的模型列表
以下语音识别模型均可通过本接口调用，实际可用范围以你的账号分组为准：
:::models audio
## 使用示例
### 转写为纯文本
最简形式：上传音频文件，拿回整段文字。`response_format` 不传时默认 `json`。
```bash
curl --request POST https://api.oairoute.com/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1"
```
### 指定语言
明确告诉模型音频的语言，能减少识别偏差、加快处理。不传时自动检测。
```bash
curl --request POST https://api.oairoute.com/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -F "file=@interview.mp3" \
  -F "model=whisper-1" \
  -F "language=zh"
```
### 带时间戳的转写
`response_format` 设为 `verbose_json` 会返回分段信息，每段带起止时间，适合做字幕。
```bash
curl --request POST https://api.oairoute.com/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -F "file=@podcast.mp3" \
  -F "model=whisper-1" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=segment"
```
### 用提示词纠正专有名词
`prompt` 可以喂一段术语表或上文，模型会倾向于用这些写法。人名、产品名、缩写多时很有用。
```bash
curl --request POST https://api.oairoute.com/v1/audio/transcriptions \
  -H "Authorization: Bearer YOUR_OAIRoute_KEY" \
  -F "file=@call.mp3" \
  -F "model=whisper-1" \
  -F "prompt=本次会议涉及 OAIRoute、Seedance、Claude Sonnet 等术语。"
```
**Whisper-1 音频转录{Whisper-1 transcription}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/audio/transcriptions' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --form 'file=@audio.mp3' \
  --form 'model=whisper-1' \
  --form 'language=zh' \
  --form 'response_format=json'
```
**Whisper-1 音频转录{Whisper-1 transcription}::Python**
```
import requests
with open("audio.mp3", "rb") as f:
    res = requests.post(
        "https://api.oairoute.com/v1/audio/transcriptions",
        headers={"Authorization": "Bearer YOUR_OAIRoute_KEY"},
        files={"file": f},
        data={
            "model": "whisper-1",
            "language": "zh",
            "response_format": "verbose_json",
        },
    )
body = res.json()
print(body["text"])
for seg in body.get("segments", []):
    print(f"[{seg['start']:.1f}-{seg['end']:.1f}] {seg['text']}")
```
**Whisper-1 音频转录{Whisper-1 transcription}::JavaScript**
```
const fd = new FormData();
fd.append("file", fileInput.files[0]);
fd.append("model", "whisper-1");
fd.append("language", "zh");
const res = await fetch(
  "https://api.oairoute.com/v1/audio/transcriptions",
  {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_OAIRoute_KEY" },
    body: fd,   // 不要手动设 Content-Type，交给浏览器生成 boundary
  }
);
const { text } = await res.json();
console.log(text);
```
**200 Whisper-1 音频转录{Whisper-1 transcription}**
```
{
  "text": "这是一段测试音频的转录文本内容。"
}
```