# Speech & audio

> Transcribe, translate, and synthesize speech with /v1/audio/transcriptions, /v1/audio/translations, and /v1/audio/speech — multipart and JSON requests, formats, and billing.

MirAPI exposes three OpenAI-compatible audio endpoints — transcription, translation, and text-to-speech — so you can turn speech into text, translate audio into English, and generate speech from text. All three use the OpenAI protocol: authenticate with `Authorization: Bearer` and point your OpenAI SDK at `https://api.mirapi.ai/v1`.

| Endpoint | What it does | Request | Response |
|---|---|---|---|
| `POST /v1/audio/transcriptions` | Transcribe audio to text | `multipart/form-data` | JSON with a `text` field |
| `POST /v1/audio/translations` | Translate audio to English | `multipart/form-data` | JSON with a `text` field |
| `POST /v1/audio/speech` | Synthesize speech from text | JSON body | Raw audio bytes |

:::tip
**Pick the right model.** Transcription and translation need a speech-to-text model; `/v1/audio/speech` needs a text-to-speech model. `deepseek-chat` in the examples below is a stand-in — replace it with the exact model name from your catalogue that supports the task.
:::

## Transcribing and translating

Both endpoints take the audio file as `multipart/form-data`; `file` and `model` are required. `transcriptions` returns the text in the language of the audio (or the one you set with `language`), while `translations` always returns English.

### Uploading a file

```bash
curl https://api.mirapi.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $MIRAPI_API_KEY" \
  -F file=@speech.mp3 \
  -F model="deepseek-chat" \
  -F response_format="json"
```

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.mirapi.ai/v1", api_key=os.environ["MIRAPI_API_KEY"])

with open("speech.mp3", "rb") as audio:
    transcript = client.audio.transcriptions.create(
        model="deepseek-chat",
        file=audio,
        response_format="json",
    )

print(transcript.text)
```

Swap the path in the URL to `/v1/audio/translations` for translation — the request shape is the same.

### Parameters

| Field | Type | Required | Notes |
|---|---|---|---|
| `file` | binary | Yes | The audio file |
| `model` | string | Yes | Speech-to-text model name from the catalogue |
| `language` | string | No | ISO-639-1 language code (`transcriptions` only) |
| `prompt` | string | No | Context or terminology hint to steer the transcript |
| `response_format` | string | No | `json` (default), `text`, `srt`, `verbose_json`, `vtt` |
| `temperature` | number | No | Sampling temperature |
| `timestamp_granularities` | array | No | `word` and/or `segment` (`transcriptions` only) |

`translations` accepts the same fields except `language` and `timestamp_granularities`.

### Response formats

`response_format` controls the shape of the result:

- `json` (default) — a JSON object with a `text` field.
- `text` — the transcript as plain text.
- `srt` and `vtt` — subtitle files.
- `verbose_json` — a detailed JSON object with segment-level detail; add `timestamp_granularities` (`word` / `segment`) to control the timestamp granularity.

## Text-to-speech

`/v1/audio/speech` takes a JSON body with the text, a voice, and a format, and returns **raw audio bytes** — not JSON. Save or stream the response body directly.

### Generating speech

```bash
curl https://api.mirapi.ai/v1/audio/speech \
  -H "Authorization: Bearer $MIRAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek-chat",
  "input": "Hello from MirAPI",
  "voice": "alloy",
  "response_format": "mp3"
  }' \
  -o speech.mp3
```

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.mirapi.ai/v1", api_key=os.environ["MIRAPI_API_KEY"])

response = client.audio.speech.create(
    model="deepseek-chat",
    input="Hello from MirAPI",
    voice="alloy",
    response_format="mp3",
)

response.stream_to_file("speech.mp3")
```

### Parameters

| Field | Type | Required | Notes |
|---|---|---|---|
| `model` | string | Yes | Text-to-speech model name from the catalogue |
| `input` | string | Yes | Text to synthesize (up to 4096 characters) |
| `voice` | string | Yes | `alloy`, `echo`, `fable`, `onyx`, `nova`, or `shimmer` |
| `response_format` | string | No | `mp3` (default), `opus`, `aac`, `flac`, `wav`, `pcm` |
| `speed` | number | No | 0.25–4.0 (default 1.0); supported where the model allows it |

### Output formats

Choose the output format with `response_format`. `mp3`, `opus`, and `aac` are compressed; `flac` is lossless; `wav` and `pcm` are uncompressed — prefer compressed formats for storage and uncompressed ones when fidelity matters more than size. The response body is the audio itself, so pipe it straight to a file.

## Choosing a model

Audio endpoints only work with models that support the task. For `/v1/audio/speech` pick a model with audio **output**; for transcription and translation pick a speech-to-text model. Browse the catalogue at https://console.mirapi.ai or query `GET /v1/models`, check each model's capabilities, and send the exact `id` it returns. A `vendor/` prefix you may see in the console is browse-only — it is not part of a request.

## Errors, billing, and logs

- **Errors** follow the standard status codes: `401` for a missing or invalid key, `403` for a valid key that is rejected (for example an exhausted balance or a model not on the key's whitelist), `413` for a file that is too large, `429` for rate limiting, and `500` for an upstream failure. For `429`, retry with exponential backoff — the gateway does not send a `Retry-After` header. Every error message ends with a request ID; include it in support tickets.
- **Billing** is per model, in USD, and shown on each catalogue entry. Audio requests appear in the console billing log and in `GET /api/log/token`, with the account-level summary in `GET /api/usage/token`. When your balance runs out, requests fail with `403` — top up and the same key works again.

## Related links

- [Models & pricing](/docs/models) — how to pick a model and read its price
- [Billing & top-ups](/docs/billing) — balances, pricing units, and reconciliation
- [Realtime speech](/docs/guides/realtime) — live speech-to-speech over WebSocket