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

# Speech to text

> Transcribe audio with POST /v1/audio/transcriptions, or turn speech in any language into English text with POST /v1/audio/translations.

Upload an audio file to `POST /v1/audio/transcriptions` and NagaAI returns the words that were spoken. To get English text from speech in another language, upload the file to `POST /v1/audio/translations` instead. Both endpoints take a multipart form and follow the OpenAI Audio format, so the OpenAI SDK works unchanged.

## Transcribe a file

The example transcribes the `speech.mp3` file from [Text to speech](https://docs.naga.ac/guides/text-to-speech.md). Choose a model whose `operations` include `transcription` in [`GET /v1/models`](https://docs.naga.ac/get-started/models).

```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.naga.ac/v1", api_key=os.environ["NAGA_API_KEY"])

with open("speech.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe",
        file=audio,
        language="en",
    )

print(transcript.text)
```

```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.naga.ac/v1", apiKey: process.env.NAGA_API_KEY });

const transcript = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: fs.createReadStream("speech.mp3"),
  language: "en",
});

console.log(transcript.text);
```

```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
curl https://api.naga.ac/v1/audio/transcriptions \
  -H "Authorization: Bearer $NAGA_API_KEY" \
  -F model=gpt-4o-transcribe \
  -F file=@speech.mp3 \
  -F language=en
```

The answer is JSON with one field:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
{"text": "Your order has shipped and will arrive on Thursday."}
```

NagaAI ignores `response_format`, `timestamp_granularities` and `temperature`, so the answer is always this JSON. There are no timestamps and no SRT or VTT output.

## Send the audio

`file` accepts mp3, wav, m4a, ogg, flac, webm and other common audio formats. When the model needs a different container, NagaAI converts the file for you. The whole request can be up to 32 MiB, so cut long recordings into parts and join the text.

`language` is the language spoken in the audio, as a lower-case ISO 639-1 code such as `en` or `de`. `prompt` is a hint for spelling and style, such as product names or jargon the clip contains.

## Translate speech

Call `client.audio.translations.create` with `whisper-large-v3`, or send the same form to `POST /v1/audio/translations`. Not every transcription model translates: `whisper-large-v3-turbo` transcribes only. The answer is English text in the same `{"text": "..."}` shape. `language` still names the language of your audio, and the translation is always into English.

```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.naga.ac/v1", api_key=os.environ["NAGA_API_KEY"])

with open("question.mp3", "rb") as audio:
    translation = client.audio.translations.create(
        model="whisper-large-v3",
        file=audio,
    )

print(translation.text)
```

```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.naga.ac/v1", apiKey: process.env.NAGA_API_KEY });

const translation = await client.audio.translations.create({
  model: "whisper-large-v3",
  file: fs.createReadStream("question.mp3"),
});

console.log(translation.text);
```

```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-dimmed"}}
curl https://api.naga.ac/v1/audio/translations \
  -H "Authorization: Bearer $NAGA_API_KEY" \
  -F model=whisper-large-v3 \
  -F file=@question.mp3
```

## Troubleshooting

### 400 with `The audio file you sent is invalid`

NagaAI could not decode the file. Check that it plays locally and isn't cut off, then upload it again.

### 400 on `language`

The code must be two lower-case letters, such as `en`. Names like `English` and codes like `EN` or `en-US` fail.

### 400 with `body.file: Field required`

The form has no `file` part. Send `multipart/form-data` and name the part `file`.

### 400 with `does not support translate`

The model transcribes but doesn't translate. Send the file to `POST /v1/audio/translations` with `whisper-large-v3`, or use `POST /v1/audio/transcriptions` to keep the original language.

### 400 `model_not_found`

The model does not exist or has no `transcription` operation (`translation` for the translations endpoint). Check its `operations` in `GET /v1/models`.

### 413

The request is over 32 MiB. Split the recording and send the parts one by one.


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