# GPT-4o mini Transcribe

This document describes how to call the Azure OpenAI `gpt-4o-mini-transcribe` speech-to-text model via the UModelVerse platform.

The model transcribes audio files into text. Compared to the Whisper model, it offers a lower Word Error Rate (WER) and better multilingual recognition, and is billed per token.

> **Official Documentation Reference**: [Azure OpenAI Create Transcription](https://learn.microsoft.com/en-us/azure/foundry-classic/openai/reference-preview-latest#create-transcription)

## Supported Models

| Model | Description |
| :--- | :--- |
| `gpt-4o-mini-transcribe` | Speech-to-text model based on GPT-4o mini. Supports multiple languages, billed per token, suitable for high-concurrency transcription scenarios. |

## Endpoint

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

This endpoint is compatible with the OpenAI `/v1/audio/transcriptions` interface.

## Request Parameters

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

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :------- | :----- | :--- |
| `model` | string | Yes | — | Model name, fixed value: `gpt-4o-mini-transcribe` |
| `file` | file | Yes | — | The audio file to transcribe. Supported formats: `flac`, `m4a`, `mp3`, `mp4`, `mpga`, `ogg`, `wav`, `webm`. Note: the `.oga` extension is not supported; use `.ogg` instead |
| `language` | string | No | — | Audio language, ISO-639-1 format (e.g., `zh`, `en`, `ja`). Specifying the language explicitly improves accuracy and latency |
| `prompt` | string | No | — | Optional text to guide the model's transcription style. Must match the audio language. Can be used to continue a previous audio segment or unify terminology |
| `response_format` | string | No | `json` | Output format. Allowed values: `json`, `text` (`gpt-4o-mini-transcribe` does not support `verbose_json`, `vtt`, `srt`) |
| `temperature` | number | No | `0` | Sampling temperature, range 0–1. When set to 0, the model auto-adjusts; higher values produce more diverse output, lower values are more deterministic |
| `stream` | boolean | No | `false` | Whether to return transcription results as a stream (SSE). When set to `true`, the endpoint returns `text/event-stream`, incrementally pushing `transcript.text.delta` events token by token, ending with a `transcript.text.done` event (containing the full text and usage) and `[DONE]`. Suitable for long audio scenarios where the client does not need to wait for the entire transcription to complete |
| `include[]` | array | No | — | Additional information to include in the response. Allowed value: `logprobs` (returns the log probability of each token, useful for evaluating model confidence). Only effective when `response_format=json`. Can be passed multiple times, e.g., `-F "include[]=logprobs"` |

## Request Examples

> If you are on Windows, we recommend using Postman or another API calling tool.

### 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"
```

Specify the language (improves accuracy):

```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"])
```

### Streaming Transcription (`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` disables curl buffering to ensure real-time streaming output.

### Returning 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

### Default (`response_format=json`)

| Field | Type | Description |
| :--- | :--- | :--- |
| `text` | string | The transcribed text |
| `usage` | object | Token usage information |
| `usage.type` | string | Fixed value `tokens` |
| `usage.total_tokens` | integer | Total token count |
| `usage.input_tokens` | integer | Input token count (including audio) |
| `usage.input_token_details.text_tokens` | integer | Text input token count |
| `usage.input_token_details.audio_tokens` | integer | Audio input token count |
| `usage.output_tokens` | integer | Output token count |

```json
{
  "text": "The weather is nice today, let's go for a walk in the park.",
  "usage": {
    "type": "tokens",
    "total_tokens": 56,
    "input_tokens": 50,
    "input_token_details": {
      "text_tokens": 0,
      "audio_tokens": 50
    },
    "output_tokens": 6
  }
}
```

### Verbose (`response_format=verbose_json`)

> ⚠️ `gpt-4o-mini-transcribe` does not support `verbose_json` and will return an error if used. For verbose format, use the `whisper-1` model instead.

### Streaming (`stream=true`)

Returns `text/event-stream`, incrementally pushing tokens. Event format:

| Event type | Meaning |
| :--- | :--- |
| `transcript.text.delta` | Incremental text fragment; the `delta` field is the newly added token |
| `transcript.text.done` | Transcription complete; the `text` field is the full text, `usage` is the token usage |

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

data: {"type":"transcript.text.delta","delta":" weather"}

data: {"type":"transcript.text.done","text":"The weather is nice today.","usage":{"type":"tokens","total_tokens":56,"input_tokens":50,"output_tokens":6}}

data: [DONE]
```

> If `include[]=logprobs` is also passed, each `delta` and `done` event will additionally carry a `logprobs` array.

### logprobs (`include[]=logprobs`)

The non-streaming response additionally returns a `logprobs` field containing the log probability and byte information for each output 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": {...}
}
```

### Plain Text (`response_format=text`)

Returns the transcribed text string directly, without JSON wrapping.

## Error Response

```json
{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "code": "error_code",
    "param": "<request ID, for feedback or troubleshooting>"
  }
}
```

## Notes

1. **Audio Formats**: Supports mainstream formats such as `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`, `mpga`. File size limit is 25 MB. The `.oga` extension is not supported (use `.ogg` instead); the `mpeg` format may produce inaccurate transcriptions due to lower mp2 encoding quality.
2. **Language Specification**: If `language` is not provided, the model auto-detects, but specifying the language explicitly usually yields more accurate results.
3. **Billing**: Billed per token; input (audio) and output (text) are billed separately, unlike Whisper which is billed per minute.
4. **Response Format**: `gpt-4o-mini-transcribe` only supports `json` and `text`; `verbose_json`, `vtt`, `srt`, etc. are not supported and will return an error if used.
5. **Temperature Out of Range**: When `temperature` exceeds 1, Azure does not return an error, but the output may contain garbled text. Ensure the value is within 0–1.
6. **Streaming Response**: `stream=true` is suitable for long audio scenarios where the client can display transcription progress in real time. Both streaming and non-streaming are billed per token with the same usage.
7. **logprobs**: `include[]=logprobs` only takes effect when `response_format=json` (default), and can be used together with `stream=true`.