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.

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.

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 for request limits.

Transcribe audio

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

The response has the transcript in text. Audio with no speech returns 422 no_speech and isn’t charged.

Refinement

We refine every transcript for accuracy, in all languages, at no extra charge. 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

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 Voices for the options.

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

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 Languages for the 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. See Billing 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.