# GPT-4o mini Transcribe 语音转文字

本文介绍 `modelverse` 接入的 Azure OpenAI `gpt-4o-mini-transcribe` 语音转文字模型的调用参数，供您使用接口时查阅。

该模型将音频文件转录为文字，相比 Whisper 模型具有更低的词错误率（WER）和更好的多语言识别能力，按 token 计费。

> 参考官方文档：[Azure OpenAI Create Transcription](https://learn.microsoft.com/en-us/azure/foundry-classic/openai/reference-preview-latest#create-transcription)

## 支持的模型

| 模型 | 说明 |
| :--- | :--- |
| `gpt-4o-mini-transcribe` | 基于 GPT-4o mini 的语音转录模型，支持多语言，按 token 计费，适合高并发转录场景。 |

## 接口

`POST https://api.modelverse.cn/v1/audio/transcriptions`

该接口与 OpenAI `/v1/audio/transcriptions` 兼容。

## 请求参数

**Content-Type**: `multipart/form-data`

| 参数 | 类型 | 是否必选 | 默认值 | 描述 |
| :--- | :--- | :------- | :----- | :--- |
| `model` | string | 是 | — | 模型名称，固定填 `gpt-4o-mini-transcribe` |
| `file` | file | 是 | — | 待转录的音频文件。支持格式：`flac`、`m4a`、`mp3`、`mp4`、`mpga`、`ogg`、`wav`、`webm`。注意：不支持 `.oga` 扩展名，请使用 `.ogg` 代替 |
| `language` | string | 否 | — | 音频语言，ISO-639-1 格式（如 `zh`、`en`、`ja`）。显式指定语言可提升准确率和响应速度 |
| `prompt` | string | 否 | — | 引导模型转录风格的提示词，需与音频语言一致。可用于续接前段音频或统一术语表达 |
| `response_format` | string | 否 | `json` | 输出格式。可选值：`json`、`text`（`gpt-4o-mini-transcribe` 不支持 `verbose_json`、`vtt`、`srt`） |
| `temperature` | number | 否 | `0` | 采样温度，范围 0–1。设为 0 时模型自动调节；较高值使输出更多样，较低值更确定 |
| `stream` | boolean | 否 | `false` | 是否以流式（SSE）返回转录结果。设为 `true` 时，接口返回 `text/event-stream`，逐 token 增量推送 `transcript.text.delta` 事件，最后以 `transcript.text.done` 事件（含完整文本和 usage）和 `[DONE]` 结束。适合长音频场景，客户端无需等待全部转写完成 |
| `include[]` | array | 否 | — | 额外返回的信息。可选值：`logprobs`（返回每个 token 的对数概率，用于评估模型置信度）。仅 `response_format=json` 时生效。可重复传多个值，如 `-F "include[]=logprobs"` |

## 请求示例

⚠️ 如果您使用 Windows 系统，建议使用 Postman 或其他 API 调用工具。

### curl

```bash
curl https://api.modelverse.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "model=gpt-4o-mini-transcribe" \
  -F "file=@/path/to/audio.mp3"
```

指定语言（提升准确率）：

```bash
curl https://api.modelverse.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "model=gpt-4o-mini-transcribe" \
  -F "file=@/path/to/audio.mp3" \
  -F "language=zh"
```

### Python

```python
import os
import requests

with open("/path/to/audio.mp3", "rb") as f:
    resp = requests.post(
        "https://api.modelverse.cn/v1/audio/transcriptions",
        headers={"Authorization": f"Bearer {os.getenv('MODELVERSE_API_KEY')}"},
        files={"file": f},
        data={"model": "gpt-4o-mini-transcribe", "language": "zh"},
    )

print(resp.json()["text"])
```

### 流式转录（`stream=true`）

```bash
curl -N https://api.modelverse.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "model=gpt-4o-mini-transcribe" \
  -F "file=@/path/to/audio.mp3" \
  -F "stream=true"
```

> `-N` 禁用 curl 缓冲，确保实时看到流式输出。

### 返回 logprobs（`include[]=logprobs`）

```bash
curl https://api.modelverse.cn/v1/audio/transcriptions \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -F "model=gpt-4o-mini-transcribe" \
  -F "file=@/path/to/audio.mp3" \
  -F "include[]=logprobs"
```

## 响应格式

### 默认（`response_format=json`）

| 字段 | 类型 | 描述 |
| :--- | :--- | :--- |
| `text` | string | 转录后的文字 |
| `usage` | object | Token 用量信息 |
| `usage.type` | string | 固定值 `tokens` |
| `usage.total_tokens` | integer | 总 token 数 |
| `usage.input_tokens` | integer | 输入 token 数（含音频） |
| `usage.input_token_details.text_tokens` | integer | 文本输入 token 数 |
| `usage.input_token_details.audio_tokens` | integer | 音频输入 token 数 |
| `usage.output_tokens` | integer | 输出 token 数 |

```json
{
  "text": "今天天气真好，我们去公园散步吧。",
  "usage": {
    "type": "tokens",
    "total_tokens": 56,
    "input_tokens": 50,
    "input_token_details": {
      "text_tokens": 0,
      "audio_tokens": 50
    },
    "output_tokens": 6
  }
}
```

### 详细（`response_format=verbose_json`）

> ⚠️ `gpt-4o-mini-transcribe` 不支持 `verbose_json`，使用时会返回错误。如需详细格式，请使用 `whisper-1` 模型。

### 流式（`stream=true`）

返回 `text/event-stream`，逐 token 增量推送，事件格式如下：

| 事件 type | 含义 |
| :--- | :--- |
| `transcript.text.delta` | 增量文本片段，字段 `delta` 为本次新增的 token |
| `transcript.text.done` | 转写完成，字段 `text` 为完整文本，`usage` 为 token 用量 |

```
data: {"type":"transcript.text.delta","delta":"今天"}

data: {"type":"transcript.text.delta","delta":"天气"}

data: {"type":"transcript.text.done","text":"今天天气真好。","usage":{"type":"tokens","total_tokens":56,"input_tokens":50,"output_tokens":6}}

data: [DONE]
```

> 若同时传 `include[]=logprobs`，每个 `delta` 和 `done` 事件都会额外携带 `logprobs` 数组。

### logprobs（`include[]=logprobs`）

非流式响应额外返回 `logprobs` 字段，包含每个输出 token 的对数概率和字节信息：

```json
{
  "text": "Is this a test?",
  "logprobs": [
    {"token": "Is", "logprob": -0.81, "bytes": [73, 115]},
    {"token": " this", "logprob": -0.91, "bytes": [32, 116, 104, 105, 115]}
  ],
  "usage": {...}
}
```

### 纯文本（`response_format=text`）

直接返回转录文字字符串，不含 JSON 包装。

## 错误响应

```json
{
  "error": {
    "message": "错误描述信息",
    "type": "invalid_request_error",
    "code": "error_code",
    "param": "<请求 ID，用于反馈或排查错误原因>"
  }
}
```

## 注意事项

1. **音频格式**：支持 `mp3`、`wav`、`m4a`、`flac`、`ogg`、`flac`、`webm`、`mpga` 等主流格式，文件大小上限 25 MB。不支持 `.oga` 扩展名（请使用 `.ogg` 代替），`mpeg` 格式因编码质量较低可能导致识别不准确。
2. **语言指定**：不传 `language` 时模型自动检测，但显式指定语言通常能获得更准确的结果。
3. **计费方式**：按 token 计费，输入（音频）和输出（文字）分别计费，与 Whisper 按分钟计费不同。
4. **响应格式**：`gpt-4o-mini-transcribe` 仅支持 `json` 和 `text` 两种格式；`verbose_json`、`vtt`、`srt` 等格式不被支持，使用时会返回错误。
5. **temperature 越界**：`temperature` 超过 1 时 Azure 不会报错，但输出可能出现乱码，请确保在 0–1 范围内。
6. **流式响应**：`stream=true` 适合长音频场景，客户端可实时展示转写进度。流式和非流式均按 token 计费，用量一致。
7. **logprobs**：`include[]=logprobs` 仅在 `response_format=json`（默认）时生效，与 `stream=true` 可同时使用。