> ## Documentation Index
> Fetch the complete documentation index at: https://developers.namuai-lab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Speech to text

> Turn recordings and voice notes into text, in Hausa, Zarma or French.

5 min

Speech to text: from a voice note to text

## Overview

`POST /v1/transcribe` takes a recording and returns what was said, as text. People in the Sahel send voice notes far more than they type: transcription lets your app read them, search them, file them or reply to them.

* **Model:** `speech-recognition` (beta)
* **Languages:** Hausa `ha` (default), Zarma `dje`, French `fr`
* **Input:** WAV, MP3, M4A/AAC, OGG/Opus, WebM or FLAC; up to 25 MB and 5 minutes
* **Counts:** the length of the audio you send

## Quickstart

Send the file as a multipart field named `file`, with the language beside it:

```bash curl theme={null}
curl https://api.namuai-lab.com/v1/transcribe \
  -H "Authorization: Bearer $NAMU_API_KEY" \
  -F file=@voice-note.ogg \
  -F language=ha
```

```python Python theme={null}
import os
import requests

with open("voice-note.ogg", "rb") as audio:
    response = requests.post(
        "https://api.namuai-lab.com/v1/transcribe",
        headers={"Authorization": f"Bearer {os.environ['NAMU_API_KEY']}"},
        files={"file": audio},
        data={"language": "ha"},
        timeout=300,
    )
response.raise_for_status()
print(response.json()["text"])
```

```javascript JavaScript theme={null}
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("voice-note.ogg")]), "voice-note.ogg");
form.append("language", "ha");

const response = await fetch("https://api.namuai-lab.com/v1/transcribe", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NAMU_API_KEY}` },
  body: form,
});
const { text } = await response.json();
```

```json Response theme={null}
{
  "model": "speech-recognition",
  "text": "sannu da zuwa",
  "language": "ha",
  "audio_seconds": 2.0
}
```

### Sending the audio as the body

If your recording is already in memory, you can send the bytes as the whole request body and put `language` in the query string. Useful from a phone, where building a multipart form is extra work:

```bash theme={null}
curl "https://api.namuai-lab.com/v1/transcribe?language=dje" \
  -H "Authorization: Bearer $NAMU_API_KEY" \
  --data-binary @message.m4a
```

## Request

**file** `file` *required*

The recording. The API recognises the container from the file itself, so the file name and content type do not matter.

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

The language spoken: `ha`, `dje` or `fr`. The model does not detect it: send the language you expect.

## Supported audio

| Format | Typical source |
| - | - |
| OGG / Opus | WhatsApp and Telegram voice notes, Android recorders |
| M4A / AAC / MP4 / 3GP | iPhone voice memos, many Android phones |
| MP3 | Radio clips, downloads |
| WAV | Studio and computer recordings |
| WebM | Recordings made in a web browser (`MediaRecorder`) |
| FLAC | Archives |

A file the API cannot read returns `415 unsupported_audio`. More in [audio formats](https://developers.namuai-lab.com/guides/audio-formats.md).

## Reading the result

* `text` is in lower case, without punctuation. Add capital letters and full stops yourself if you show it to people.
* `audio_seconds` is the length of what you sent, which is what was counted.
* An empty recording returns `400 empty_audio`.

## Best practices

> [accordion] Record close to the speaker
>
> Most errors come from distance and noise, not language. A phone held near the mouth, out of the wind, gives far better text than one on a table across the room.

> [accordion] Send the language people actually speak
>
> If a user picked Zarma in your app, send `dje`. For mixed Hausa and French speech, send the language most of it is in.

> [accordion] Do not convert before sending
>
> Send the voice note as it is. Converting an OGG to WAV first makes the upload about ten times larger and does not improve the text.

> [accordion] Cut long recordings
>
> Up to 5 minutes per request. For a longer meeting or programme, cut it at silences into pieces under 5 minutes and send them in order. See [long recordings](https://developers.namuai-lab.com/guides/audio-formats.md#long-recordings).

> [accordion] Check what matters
>
> Transcripts can be wrong, especially for names, numbers and noisy audio. When the text drives a decision (a dose, an amount, an address), show it back to the person or have someone check it.

## Limits

* 25 MB and 300 seconds per file (`413 payload_too_large`, `413 audio_too_long`).
* One language per request; no automatic language detection.
* No timestamps or speaker labels yet.

## Related

> [card] [Transcribe a voice note](https://developers.namuai-lab.com/tutorials/transcribe-a-voice-note.md)
>
> Tutorial

> [card] [Translation](https://developers.namuai-lab.com/capabilities/translation.md)
>
> Speech straight to French or Hausa

> [card] [API reference](https://developers.namuai-lab.com/api-reference/transcription/create-transcription.md)
>
> POST /v1/transcribe


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