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

# Speech-to-Text

> MiniMax ASR transcribes audio to text, with streaming, speaker diarization and subtitle export — ready for meeting minutes, podcast/video transcription, content moderation and call QA.

To use speech recognition, either [Pay-as-you-go](/docs/guides/pricing-paygo#speech) or [subscribe to Token Plan](/docs/guides/pricing-token-plan).

## Overview

MiniMax ASR turns audio into text. The current public model is `asr-1.0`:

* **Multilingual & code-switching**: without a `language` hint the model auto-detects the dominant language and handles Chinese-English code-switching; you can still pin a language via the `language` header.
* **One-shot or streaming**: default is one-shot; set `stream=true` to receive incremental `delta` chunks over SSE for live captions and low-latency voice agents.
* **Speaker diarization**: with `response_format=verbose_json` the response includes `n_speakers` and per-segment `speaker` tags, answering "who said what and when".
* **Precise timestamps & subtitle export**: `verbose_json` reports segment-level start/end; you can also request `srt` or `vtt` directly.
* **Robustness**: the model is specifically tuned to reduce hallucinations, delivering a significant boost in real-world usability under noise, colloquial speech and jargon.

## Capabilities

| Capability                 | How to enable                     | Typical use                                                   |
| :------------------------- | :-------------------------------- | :------------------------------------------------------------ |
| Plain transcription        | `response_format=json` (default)  | Text-only output                                              |
| Streaming                  | `stream=true`, `json` only        | Live captions, on-the-fly transcription, low-latency voice UX |
| Diarization + timestamps   | `response_format=verbose_json`    | Meeting minutes, interview cleanup, multi-party call QA       |
| Subtitle export            | `response_format=srt` or `vtt`    | Ready-to-import subtitles for editors and players             |
| Multilingual / code-switch | Omit `language`, or pin as needed | Cross-language meetings, bilingual podcasts, localization     |

<Note>
  `verbose_json` / `srt` / `vtt` enable diarization and timestamp alignment, so they **cannot be combined with `stream=true`**.
</Note>

## Baseline specs

### Audio file

| Item          | Constraint                                                                                        |
| :------------ | :------------------------------------------------------------------------------------------------ |
| Formats       | `wav` / `aiff` / `flac` / `alac`(m4a) / `mp3` / `aac` / `opus` / `ogg`                            |
| Duration      | Up to **500 seconds** per request; longer audio returns `400` and is **not** truncated            |
| Size          | Up to **50 MB** per request; larger payloads return `413`                                         |
| Not supported | Raw PCM without a container; audio-side streaming input (do client-side VAD for pseudo-streaming) |

<Note>
  ASR does not need high sample rates or stereo. Uncompressed high-fidelity audio easily blows past the 50 MB limit (500 s / 48 kHz stereo WAV ≈ 92 MB). Convert to **mono 16 kHz**, or use `mp3` / `aac` / `opus` — accuracy is unaffected.
</Note>

### Supported languages

If `language` is omitted (or empty), multilingual / code-switching recognition is enabled and the model picks the dominant language automatically. When the language is known, pin it explicitly — it typically yields more stable results on short clips and jargon-heavy content.

| Group               | Languages (BCP-47 tag)                                                                                                         |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------- |
| Chinese & East Asia | Chinese `zh`, Cantonese `yue`, Japanese `ja`, Korean `ko`                                                                      |
| Southeast Asia      | Thai `th`, Vietnamese `vi`, Indonesian `id`, Malay `ms`, Filipino `fil`                                                        |
| Europe & Americas   | English `en`, French `fr`, German `de`, Spanish `es`, Italian `it`, Portuguese `pt`, Polish `pl`, Russian `ru`, Ukrainian `uk` |
| Others              | Arabic `ar`, Turkish `tr`                                                                                                      |

### Response formats

Controlled by the `response_format` parameter; the available values are:

| Value            | Content type       | Main fields / body                                                                   |
| :--------------- | :----------------- | :----------------------------------------------------------------------------------- |
| `json` (default) | `application/json` | `text` + `duration` + `trace_id`                                                     |
| `verbose_json`   | `application/json` | `text` + `duration` + `n_speakers` + `segments[]` (speaker & per-segment timestamps) |
| `srt`            | `text/plain`       | Standard SRT subtitles                                                               |
| `vtt`            | `text/vtt`         | WebVTT subtitles                                                                     |

In streaming mode `response_format` must be `json`. Events are pushed line by line as `data: <json>` with fields `index` / `delta` / `finish` / `duration` (only the terminating event carries `duration`).

## Features & code samples

Grab an API key from [Account → API Keys](https://platform.minimaxi.com/user-center/basic-information/interface-key) and put it into the `MINIMAX_API_KEY` env var.

### One-shot transcription (default)

<CodeGroup>
  ```python theme={null}
  import os, requests

  api_key = os.getenv("MINIMAX_API_KEY")
  url = "https://api.minimaxi.com/v1/speech_to_text"
  headers = {"Authorization": f"Bearer {api_key}"}

  with open("/path/to/audio.mp3", "rb") as f:
      files = {"file": ("audio.mp3", f)}
      data = {"model": "asr-1.0"}
      response = requests.post(url, headers=headers, data=data, files=files)

  response.raise_for_status()
  print(response.json())
  # {"text": "...", "duration": 26.325, "trace_id": "..."}
  ```

  ```bash theme={null}
  curl --location 'https://api.minimaxi.com/v1/speech_to_text' \
    --header "Authorization: Bearer ${MINIMAX_API_KEY}" \
    --form 'model="asr-1.0"' \
    --form 'file=@"/path/to/audio.mp3"'
  ```
</CodeGroup>

### Pin a language

<CodeGroup>
  ```python theme={null}
  import os, requests

  api_key = os.getenv("MINIMAX_API_KEY")
  url = "https://api.minimaxi.com/v1/speech_to_text"
  headers = {"Authorization": f"Bearer {api_key}", "language": "en"}

  with open("/path/to/podcast.mp3", "rb") as f:
      files = {"file": ("podcast.mp3", f)}
      data = {"model": "asr-1.0"}
      print(requests.post(url, headers=headers, data=data, files=files).json())
  ```

  ```bash theme={null}
  curl --location 'https://api.minimaxi.com/v1/speech_to_text' \
    --header "Authorization: Bearer ${MINIMAX_API_KEY}" \
    --header 'language: en' \
    --form 'model="asr-1.0"' \
    --form 'file=@"/path/to/podcast.mp3"'
  ```
</CodeGroup>

### Diarization with per-segment timestamps

<CodeGroup>
  ```python theme={null}
  import os, requests

  api_key = os.getenv("MINIMAX_API_KEY")
  url = "https://api.minimaxi.com/v1/speech_to_text"
  headers = {"Authorization": f"Bearer {api_key}"}

  with open("/path/to/meeting.wav", "rb") as f:
      files = {"file": ("meeting.wav", f)}
      data = {"model": "asr-1.0", "response_format": "verbose_json"}
      result = requests.post(url, headers=headers, data=data, files=files).json()

  for seg in result["segments"]:
      print(f"[{seg['speaker']}] {seg['start']:.2f}-{seg['end']:.2f} {seg['text']}")
  ```

  ```bash theme={null}
  curl --location 'https://api.minimaxi.com/v1/speech_to_text' \
    --header "Authorization: Bearer ${MINIMAX_API_KEY}" \
    --form 'model="asr-1.0"' \
    --form 'response_format="verbose_json"' \
    --form 'file=@"/path/to/meeting.wav"'
  ```
</CodeGroup>

Example response:

```json theme={null}
{
  "text": "Hello everyone. Let me check the question.",
  "duration": 12.744,
  "n_speakers": 2,
  "segments": [
    {"id": 0, "start": 0.1, "end": 1.66, "speaker": "S1", "text": "Hello everyone."},
    {"id": 1, "start": 2.0, "end": 6.10, "speaker": "S2", "text": "Let me check the question."}
  ],
  "trace_id": "021785229015510a2c883cf675b9804d"
}
```

### Export SRT / VTT subtitles

<CodeGroup>
  ```python theme={null}
  import os, requests

  api_key = os.getenv("MINIMAX_API_KEY")
  url = "https://api.minimaxi.com/v1/speech_to_text"
  headers = {"Authorization": f"Bearer {api_key}"}

  with open("/path/to/video.mp3", "rb") as f:
      files = {"file": ("video.mp3", f)}
      data = {"model": "asr-1.0", "response_format": "srt"}
      resp = requests.post(url, headers=headers, data=data, files=files)

  with open("subtitle.srt", "w", encoding="utf-8") as out:
      out.write(resp.text)
  ```

  ```bash theme={null}
  curl --location 'https://api.minimaxi.com/v1/speech_to_text' \
    --header "Authorization: Bearer ${MINIMAX_API_KEY}" \
    --form 'model="asr-1.0"' \
    --form 'response_format="srt"' \
    --form 'file=@"/path/to/video.mp3"' \
    --output subtitle.srt
  ```
</CodeGroup>

### Streaming

<CodeGroup>
  ```python theme={null}
  import os, json, requests

  api_key = os.getenv("MINIMAX_API_KEY")
  url = "https://api.minimaxi.com/v1/speech_to_text"
  headers = {"Authorization": f"Bearer {api_key}"}

  with open("/path/to/audio.mp3", "rb") as f:
      files = {"file": ("audio.mp3", f)}
      data = {"model": "asr-1.0", "stream": "true"}
      with requests.post(url, headers=headers, data=data, files=files, stream=True) as resp:
          resp.raise_for_status()
          for raw in resp.iter_lines(decode_unicode=True):
              if not raw or not raw.startswith("data:"):
                  continue
              event = json.loads(raw[len("data:"):].strip())
              print(event.get("delta", ""), end="", flush=True)
              if event.get("finish"):
                  break
  ```

  ```bash theme={null}
  curl --location 'https://api.minimaxi.com/v1/speech_to_text' \
    --header "Authorization: Bearer ${MINIMAX_API_KEY}" \
    --form 'model="asr-1.0"' \
    --form 'stream="true"' \
    --form 'file=@"/path/to/audio.mp3"' \
    --no-buffer
  ```
</CodeGroup>

Wire format (events are separated by blank lines):

```
data: {"index":0,"delta":"Actually","finish":false}

data: {"index":1,"delta":" the merchant still profits.","finish":false}

data: {"index":2,"delta":"","finish":true,"duration":26.325}
```

## Errors

Errors follow OpenAI-style envelopes: the HTTP status equals the real error, body is `{"type":"error","error":{...},"request_id":"..."}`.

| HTTP  | `error.type`                 | Trigger                                            |
| :---- | :--------------------------- | :------------------------------------------------- |
| `400` | `bad_request_error`          | Invalid parameters, e.g. audio longer than 500 s   |
| `401` | `authorized_error`           | Missing or invalid API key                         |
| `402` | `insufficient_balance_error` | Not enough balance / bundle quota                  |
| `413` | `invalid_request_error`      | Body exceeds the 50 MB limit                       |
| `422` | `unprocessable_entity_error` | Audio contains sensitive content                   |
| `429` | `rate_limit_error`           | Rate-limited                                       |
| `500` | `server_error`               | Server-side error; reach out with the `request_id` |

## Further reading

<Columns cols={2}>
  <Card title="Speech-to-Text API" icon="book-open" href="/docs/api-reference/speech-to-text" arrow="true" cta="View">
    Full parameters, response schema and error codes.
  </Card>

  <Card title="Pricing" icon="book-open" href="/docs/guides/pricing-paygo#speech" arrow="true" cta="View">
    Pricing, billing rules and usage limits for every speech model.
  </Card>
</Columns>