# Transcribe a recording

A transcription model turns one recording into text. Send it as the one file of a user message; the transcript comes back as the reply’s content.

`POST https://api.momor.ai/models/transcribe`

Here `auto`, `*`, a tier and a name all reach transcription models alone. For OpenAI’s multipart shape, use [Create a transcription](/docs/gateway/reference/audio-transcriptions/).

## Body

The body is the one [Call a model](/docs/gateway/reference/chat/) takes. A transcription takes no `streaming`, `tools` or `responseSchema`.

- `systemPrompt` (string, required): Words the recording uses, passed on to the model. May be empty.
- `messages` (Message[], required): One user message carrying the recording as its one file.
  - `type` (string, required): user
  - `value` (string): May be empty.
  - `files` (File[], required): Exactly one audio/* file, sent inline as bytes. A recording sent by address is refused.
- `model` (string | object, default `auto`): Which transcription models may answer, as on Call a model.
- `models` ((string | object)[]): Several selectors, tried in order.
- `prioritization` (object): Which providers lead and which serve nothing, and zdr, zero data retention, as on Call a model.
- `keys` (object): Your own provider keys for this call.
- `parameters` (object): Sampling, as on Call a model.
  - `temperature` (number): Passed on to the model.

## Response

- `type` (string): monolith
- `model` (object): What served the call: name, tier, publisher and provider.
- `messages` (Message[]): One content message whose value is the transcript.
- `usage` (object): What the provider counted the recording as. A token count the provider does not report is left at 0.
  - `inputTokens` (integer): Input tokens, for a model priced by the token.
  - `outputTokens` (integer): Output tokens, for a model priced by the token.
  - `units` (object): The length of the recording, where the provider reports one: unit is minute and count the minutes, in fractions of a minute. A model priced by the minute is charged count times its perUnit price. Left out where the provider reports no length.

## Errors

Failures are problem documents, as on [Call a model](/docs/gateway/reference/chat/#errors). The messages particular to a transcription:

| Status | Code | What happened |
| --- | --- | --- |
| `400` | `—` | A transcription carries one recording, an audio file attached to a user message. |
| `400` | `—` | A transcription takes no stream, tools or responseSchema. |
| `400` | `—` | <model> transcribes a recording sent with the call, not one by address. |
| `404` | `—` | No transcription model answers to the name. |
| `413` | `—` | The recording is over the 10 MiB inline limit, or the body over 30 MiB. |

```bash title="Request"
curl https://api.momor.ai/models/transcribe \
  -H "Authorization: Bearer $MOMOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "whisper-large-v3",
    "systemPrompt": "",
    "messages": [{ "type": "user", "value": "",
      "files": [{ "type": "bytes", "name": "standup.mp3", "contentType": "audio/mpeg", "value": "SUQzBAAAAAAA…" }] }]
  }'
```

```python
import base64
import os
import requests

with open("standup.mp3", "rb") as recording:
    audio = base64.b64encode(recording.read()).decode()

turn = requests.post(
    "https://api.momor.ai/models/transcribe",
    headers={"Authorization": f"Bearer {os.environ['MOMOR_API_KEY']}"},
    json={
        "model": "whisper-large-v3",
        "systemPrompt": "",
        "messages": [{"type": "user", "value": "", "files": [
            {"type": "bytes", "name": "standup.mp3", "contentType": "audio/mpeg", "value": audio},
        ]}],
    },
).json()
print(turn["messages"][0]["value"])
```

```json title="Response"
{
  "type": "monolith",
  "model": { "name": "whisper-large-v3", "tier": "tierless", "publisher": "OpenAI", "provider": "groq" },
  "messages": [{ "type": "content", "value": "Morning, everyone. The checkout fix shipped last night.", "data": {} }],
  "usage": { "provider": "groq", "inputTokens": 0, "outputTokens": 0, "units": { "unit": "minute", "count": 0.07 } }
}
```