> ## 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.

Transcription, speech and translation run on GPUs that can take a few minutes to start, so each one returns a [job](https://docs.vocalistic.ai/jobs.md) right away. Send `Prefer: wait=30` to get the finished job in the same response when it's ready in time.

## Languages

Use these codes wherever a route asks for a language. You can also fetch them with `GET /v1/languages`.

| Code | Language |
| - | - |
| `yo` | Yoruba |
| `ig` | Igbo |
| `ha` | Hausa |
| `pcm` | Nigerian Pidgin |
| `en-NG` | Nigerian English |

## Voices

Pass one of these as `voice` when generating speech. You can also fetch them with `GET /v1/voices`.

| Language | Voices |
| - | - |
| Yoruba | `yo_spk0` to `yo_spk6` |
| Igbo | `ig_spk0` to `ig_spk5` |
| Hausa | `ha_spk0` to `ha_spk4` |
| Nigerian Pidgin | `pcm_spk0` to `pcm_spk7` |

Pidgin voices can also speak Nigerian English. Send `"language": "en-NG"` with a Pidgin voice.

To hear a voice, play the `preview_url` that `GET /v1/voices` returns for it. Previews are free and need no credential.

## 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. When the models are busy you'll get `503 model_busy`, with a `Retry-After` header. See [Rate limits](https://docs.vocalistic.ai/rate-limits.md) for request limits.

## Transcribe audio

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

The job's `result` has the transcript in `text`. Silent audio returns `422 no_speech` straight away. If the model finds no speech, the job fails with the same code. Neither is charged.

### Refinement

We refine every transcript for accuracy, in all languages, at no extra charge. In `result`, `text` has the refined version, `raw_text` has the original, and `refined` says whether they differ.

Refinement is on by default. To turn it off for your organization, use `PUT /v1/organization/transcript-refinement`.

## Generate speech

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

The job's `result` has `audio_url`, `format`, `duration_ms` and `sample_rate`. Download the audio with the same key. It's WAV by default, or raw PCM with `"format": "pcm"`:

```bash theme={null}
curl https://api.vocalistic.ai/v1/jobs/JOB_ID/audio \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --output speech.wav
```

See [Voices](#voices) for the options.

### Stream speech

Send `"stream": true` to receive server-sent events as the audio is generated, with no job to check:

| 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' \
  -H 'Prefer: wait=30' \
  -d '{"texts": ["How are you?"], "source": "en-NG", "target": "yo"}'
```

The job's `result` has `translations`, in the same order as `texts`. See [Languages](#languages) for the codes.

## Credits

Each job places a hold on your balance when it starts, then charges the actual cost when it finishes. If your balance can't cover the hold, you'll get `402 insufficient_credits`. See [Billing](https://docs.vocalistic.ai/billing.md) to buy more. 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.