Text to Speech

Send text, get back a WAV file of it spoken aloud. These endpoints let you create speech from your own systems, and list, fetch and delete the audio you’ve made.

Endpoint	Request
List languages	`GET /api/v2/languages/public?service=tts`
List voices	`GET /api/v2/tts/voices`
Create audio	`POST /api/v2/tts`
List audio	`GET /api/v2/tts`
Get audio	`GET /api/v2/tts/{id}`
Delete audio	`DELETE /api/v2/tts/{id}`

Authentication

Send your API key in the X-API-KEY header on every request, to the base URL https://api-eg.olimi.ai. See API Authentication. You only ever see the audio that belongs to the company your API key is issued to.

How it works

Creating audio runs in the background:

Create: Create audio returns straight away with status: "pending".
Poll: call Get audio every few seconds until status is completed or failed.
Download: once it’s completed, download the file from attachment.url. The link expires after one hour; call Get audio again for a fresh one.

Choosing a voice and language

A request needs a languageId and a voiceId. Fetch them once and cache them; they don’t change.

Language: list the languages available for speech, with List languages. It needs no API key.
Voice: list the voices for the language you picked, with List voices.

Pairing a voice with a language it isn’t valid for returns voice_language_not_compatible.

Being listed is not a guarantee that a voice works. A voice whose engine is unavailable is still listed, and its audio ends up failed. Test the voices you plan to use with a short phrase, and keep a fallback voice.

Audio fields

Field	Type	Meaning
`id`	UUID	The audio’s ID.
`name`	string	Your label, or `TTS_<timestamp>` if you didn’t send one.
`input`	string	The text that was spoken.
`status`	string	See Status values.
`duration`	integer	Length of the audio in seconds, rounded down. `0` until the audio is ready.
`responseFormat`	string	Always `pcm`: the encoding inside the WAV file, not the file type.
`languageId`	UUID	The language used.
`voiceId`	UUID	The voice used.
`attachment`	object	The audio file. See Attachment object.
`language`	object	The language’s `code` and `name`.
`voice`	object	The voice’s `id`, `name` and `voiceKey`.
`createdAt`	string	When the audio was created (ISO 8601, UTC).
`updatedAt`	string	When it was last changed (ISO 8601, UTC).

Responses also carry internal fields. They may change without notice, so rely only on the fields listed on this page.

Status values

Value	Meaning
`pending`	Still being generated. Poll again.
`completed`	Ready. Download it from `attachment.url`.
`failed`	Generation didn’t produce audio. No reason is given; retry, or try another voice.

Attachment object

Field	Type	Meaning
`id`	UUID	The file’s ID.
`originalName`	string	The file name: your `name` plus `.wav`.
`mimeType`	string	Always `audio/wav`.
`fileSize`	string	Size in bytes, as a string. `0` until the audio is ready.
`url`	string \| null	A temporary download link. Only present once `status` is `completed`. Expires after one hour.

Audio format

The file is a WAV (RIFF/WAVE) holding signed 16-bit little-endian PCM, mono. The sample rate varies by voice, because different voices run on different engines. You’ll see 24,000 Hz or 16,000 Hz. Don’t hard-code it; read it from the WAV header, which every audio library does for you:

ffprobe -v error -show_entries stream=sample_rate,channels -of csv=p=0 out.wav

Tips

Normalise numbers before sending. Spell out digits, currencies, dates and phone numbers as words ("1234" → "ألف ومتين أربعة وتلاتين"). Written-out Arabic is pronounced far more reliably than raw numerals.
Split long text. Send sentences or paragraphs rather than whole documents. Shorter requests finish faster and fail less often.
Sanity-check duration. Compare it with what you’d expect for the length of your text. A wildly different value means that request went wrong; delete it and create it again.

Errors

Always branch on statusCode first. Most errors also carry a machine-readable errorCode:

{
  "statusCode": 400,
  "errorCode": "voice_language_not_compatible",
  "message": "The selected voice does not support the selected language"
}

Status	`errorCode`	When
`400`	none	An ID in the URL or query isn’t a valid UUID, or `languageId` is missing from List voices.
`400`	`tts_language_not_supported`	The language doesn’t exist, or isn’t available for speech.
`400`	`tts_voice_not_supported`	Unknown voice, or a voice not available for speech.
`400`	`voice_language_not_compatible`	The voice belongs to a different language.
`401`	`unauthenticated`	The `X-API-KEY` header is missing or the key isn’t valid.
`404`	`tts_record_not_found`	No audio with that `id` belongs to your company, or it was deleted.
`422`	none	The request body didn’t pass validation.

If the engine behind a voice fails, you don’t get an error. The audio’s status becomes failed instead. Validation errors (422) have a different body. message is a list of what went wrong, and there’s no errorCode:

{
  "statusCode": 422,
  "message": ["input should not be empty"],
  "error": "Unprocessable Entity"
}

The message text is for humans and may change, so don’t match on it.

Getting Started

API Overview

Agents & Campaigns

Speech

Authentication

How it works

Choosing a voice and language

Audio fields

Status values

Attachment object

Audio format

Tips

Errors

​Authentication

​How it works

​Choosing a voice and language

​Audio fields

​Status values

​Attachment object

​Audio format

​Tips

​Errors

Authentication

How it works

Choosing a voice and language

Audio fields

Status values

Attachment object

Audio format

Tips

Errors