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

# Transcription

> Speech-to-text for voice input.

Accepts an audio payload and returns a transcript. Used for voice input into
planning and chat surfaces.

The request is `multipart/form-data`, not JSON — this is the only endpoint on
the platform that does not take a JSON body.

## Request

**file** `file` *required*

The audio blob. Sent as a multipart part, not base64 in a JSON field. A
missing or non-file `file` part returns `400`.

**language** `string` (default: en)

ISO language hint passed to the model.

**prompt** `string`

Biases the transcription. Defaults to a teaching-domain prompt that primes the
model for lesson planning, curriculum and assessment vocabulary, and asks for
proper punctuation and capitalisation.

**response\_format** `string` (default: json)

Passed straight through to the upstream model.

```bash cURL theme={null}
curl -X POST "$BASE_URL/whisper-transcribe" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@recording.webm" \
  -F "language=en"
```

## Response

**success** `boolean`

`true` when transcription succeeded.

**text** `string`

The transcript, trimmed.

**language** `string`

Language as reported by the model.

**duration** `number`

Audio duration as reported by the model.

```json Response theme={null}
{
  "success": true,
  "text": "Plan a four lesson unit on photosynthesis for second years.",
  "language": "english",
  "duration": 4.2
}
```

> [!NOTE]
>
> `language` and `duration` are passed through from the upstream response, so they
> are absent when the configured `response_format` does not include them. Only
> `text` is guaranteed.

## Errors

| Status | Cause |
| - | - |
| 400 | No `file` part, or the upstream model rejected the audio. |
| 405 | Anything other than `POST`. |
| 500 | Server missing its upstream API key. |
| 502 | Upstream returned a 5xx. |

Failures carry `details` alongside `error`: the upstream `status` and the first
500 characters of its body, so a rejected payload can be diagnosed without
server log access.

> [!NOTE]
>
> The model defaults to `gpt-4o-transcribe`, which supersedes `whisper-1` — the
> endpoint name predates the swap. It can be pinned back to `whisper-1` by
> environment variable without a redeploy, which is needed only for the
> `verbose_json`, `srt` and `vtt` formats that `gpt-4o-transcribe` does not
> support.

> [!WARNING]
>
> The deployed transcription proxy is richer than earlier written specifications
> of it. Treat the running service as authoritative and do not redeploy from an
> older spec document.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.