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

# Speech and translation

> Transcribe audio, generate speech and translate text.

These routes need an API key or client token with the `inference` scope. Each call spends credits. A call that fails before producing anything isn't charged.

## Limits

| Route | Limit | Error |
| - | - | - |
| `POST /v1/audio/transcriptions` | 25 MB upload | `413 file_too_large` |
| `POST /v1/audio/transcriptions` | 7 minutes of audio | `413 audio_too_long` |
| `POST /v1/audio/speech` | 1,500 characters | `400 invalid_text` |
| `POST /v1/translations` | 100 texts and 20,000 characters in total | `400 invalid_texts` |

To work with longer content, split it into separate requests. Per-key rate limits aren't enforced yet. When the models are busy you'll get `503 model_busy`, with a `Retry-After` header.

## Transcribe audio

```bash theme={null}
curl https://api.vocalistic.ai/v1/audio/transcriptions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F file=@clip.wav \
  -F language=yo
```

Audio with no speech returns `422 no_speech` and isn't charged.

> [!WARNING]
>
> By default, Yoruba transcripts are corrected by a third-party language model. If your audio is sensitive, send `fix=false` to turn this off.

## Generate speech

```bash theme={null}
curl https://api.vocalistic.ai/v1/audio/speech \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"text": "How far?", "voice": "pcm_spk7", "language": "pcm"}' \
  --output speech.wav
```

The response is audio, in WAV by default or raw PCM with `"format": "pcm"`. The `X-Credits-Charged` and `X-Sample-Rate` headers give the cost and sample rate. See `GET /v1/voices` for the available voices.

### Stream speech

Send `"stream": true` to receive server-sent events as the audio is generated:

| Event | Contains |
| - | - |
| `audio.delta` | `audio` (base64 PCM), `sample_rate` and `format` |
| `audio.done` | `duration_ms` and `usage` |
| `error` | `code`, `message`, `request_id` and `usage` |

You're charged for the audio generated, including when you disconnect early.

## Translate text

```bash theme={null}
curl https://api.vocalistic.ai/v1/translations \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"texts": ["How are you?"], "source": "en-NG", "target": "yo"}'
```

See `GET /v1/languages` for the language codes.

## Credits

Each call places a hold on your balance before it runs, then charges the actual cost when it finishes. If your balance can't cover the hold, you'll get `402 insufficient_credits`. Check your balance with `GET /v1/billing/balance`, your prices with `GET /v1/billing/rates` and your spending with `GET /v1/usage`. These need the `billing:read` and `usage:read` scopes.


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