> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 语音转文字

> POST /v1/audio/transcriptions —— Whisper / GPT-4o transcribe

把音频文件转写为文字。

## 请求

```bash theme={null}
curl https://openp.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENPAI_API_KEY" \
  -F file=@audio.mp3 \
  -F model=whisper-1 \
  -F language=zh \
  -F response_format=verbose_json
```

### 参数

| 字段                          | 类型     |  必填 | 说明                                                           |
| --------------------------- | ------ | :-: | ------------------------------------------------------------ |
| `file`                      | file   |  ✅  | 音频文件,支持 mp3 / mp4 / mpeg / mpga / m4a / wav / webm,最大 25MB   |
| `model`                     | string |  ✅  | `whisper-1` / `gpt-4o-transcribe` / `gpt-4o-mini-transcribe` |
| `language`                  | string |     | ISO-639-1 语言代码,如 `zh` / `en` / `ja`,留空自动识别                   |
| `prompt`                    | string |     | 引导词,提示模型领域 / 专有名词 / 拼写                                       |
| `response_format`           | string |     | `json`(默认) / `text` / `srt` / `verbose_json` / `vtt`         |
| `temperature`               | number |     | 0-1                                                          |
| `timestamp_granularities[]` | array  |     | `word` / `segment`,需 `verbose_json`                          |

## 响应

`response_format: "json"`:

```json theme={null}
{"text": "你好,这是一段测试音频。"}
```

`response_format: "verbose_json"`:

```json theme={null}
{
  "task": "transcribe",
  "language": "zh",
  "duration": 4.2,
  "text": "你好,这是一段测试音频。",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 4.2,
      "text": "你好,这是一段测试音频。"
    }
  ]
}
```

`srt` / `vtt` 返回字幕文本(可直接保存为 `.srt` / `.vtt`)。

## Python

```python theme={null}
from openai import OpenAI
client = OpenAI(api_key="sk-...", base_url="https://openp.ai/v1")

with open("audio.mp3", "rb") as f:
    resp = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )
print(resp.text)
```

## 长音频策略

* Whisper 单文件 25MB 上限,长音频请提前 **切片**(推荐 5-10 分钟一段)。
* 使用 `prompt` 传入上一段尾部文本以保持语境连贯。
* 工具如 `ffmpeg -i input.mp3 -f segment -segment_time 600 part_%03d.mp3` 可快速切片。

## 计费

按 **音频时长(秒)** 计费,具体倍率以控制台为准。