# Audio Transcriptions API — 语音转文字

Source: https://ofox.ai/zh/docs/api/openai/audio-transcriptions

将音频转为文字。兼容 OpenAI 的 `POST /v1/audio/transcriptions`，以 `multipart/form-data` 上传音频文件。

| 系列 | 模型 | 说明 |
|---|---|---|
| GPT 转录 | `openai/gpt-transcribe`、`openai/gpt-4o-mini-transcribe`、`openai/gpt-4o-transcribe-diarize` | 见 [GPT 转录](https://ofox.ai/zh/docs/develop/models/gpt-transcribe) |
| ElevenLabs | `elevenlabs/scribe_v2` | 支持逐词时间戳与说话人分离，见 [ElevenLabs](https://ofox.ai/zh/docs/develop/models/elevenlabs) |

## 快速开始

- base_url: `https://api.ofox.ai/v1`
- 接口地址: `https://api.ofox.ai/v1/audio/transcriptions`
- 模型 ID: `openai/gpt-transcribe`

**Python**

```python filename="transcribe.py"
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="openai/gpt-transcribe",
        file=f,
        language="zh",
        prompt="以下是普通话的句子，请使用简体中文。",
    )
print(result.text)
```

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -F model=openai/gpt-transcribe \
  -F language=zh \
  -F prompt="以下是普通话的句子，请使用简体中文。" \
  -F file=@meeting.mp3
```

## 请求参数

**file** `file` · required

音频文件，如 `mp3`、`wav`。非音频文件返回 400。

**model** `string` · required

模型 ID，见上表。

**language** `string`

音频的语言，如 `zh`、`en`。不传时自动识别。

**prompt** `string`

提示文字，用于指定用字习惯或专有名词，适用于 GPT 转录模型。转录普通话时，建议同时传入 `language: "zh"` 与「以下是普通话的句子，请使用简体中文。」，否则可能输出繁体字。

**response_format** `string` · default `json` · values `json` / `verbose_json`

仅支持 `json` 与 `verbose_json`；`text`、`srt`、`vtt` 会返回 400。`verbose_json` 仅适用于 ElevenLabs Scribe。

**provider_options** `string`

供应商专有参数，以 JSON 字符串作为表单字段传入，例如 `{"elevenlabs": {"diarize": true}}`。见各系列页。

## 响应

```json
{
  "text": "今天天气很好，我们下午三点在会议室讨论新功能。",
  "usage": { "type": "duration", "seconds": 9 }
}
```

**text** `string`

转录文字。

**usage** `object`

计费依据。`type` 为 `duration` 时按音频秒数计费（`seconds`）；为 `tokens` 时按 token 计费（`input_tokens`、`output_tokens`）。

ElevenLabs Scribe 另返回 `words`（逐词文字与起止时间）、`language`、`duration` 等字段，见 [ElevenLabs](https://ofox.ai/zh/docs/develop/models/elevenlabs#scribe)。需要字幕文件时，可根据 `words` 中的时间戳自行生成。

## 常见报错
| HTTP | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 400 | `Unsupported response_format 'srt'. Only 'json' and 'verbose_json' are supported on this gateway` | 使用了 `text`、`srt`、`vtt` | 改用 `json`；字幕请根据时间戳生成 |
| 400 | `response_format 'verbose_json' is not compatible with model 'gpt-transcribe'. Use 'json' or 'text' instead.` | GPT 转录模型不支持 `verbose_json` | 改用 `json` |
| 400 | `Unsupported file format txt` | 上传的不是音频文件 | 上传 `mp3`、`wav` 等音频 |
| 400 | `Model 'openai/gpt-5.4' is not supported on /v1/audio/transcriptions. Supported: ...` | 所选模型不是转录模型 | 改用报错中列出的模型 |
| 400 | `You must provide a model parameter.` | 以 JSON 而非表单提交了请求 | 使用 `multipart/form-data` 上传文件 |

完整的错误码说明见[错误处理](https://ofox.ai/zh/docs/develop/guides/error-handling)。