Speech to Text

Upload a recording, get back a written transcript with each speaker labelled. These endpoints let you transcribe audio from your own systems, and list, fetch, redo and delete your transcripts.

Endpoint	Request
Upload audio	`POST /api/v2/stt/upload`
List transcripts	`GET /api/v2/stt`
Get a transcript	`GET /api/v2/stt/{id}`
Regenerate a transcript	`POST /api/v2/stt/{id}/regenerate`
Delete a transcript	`DELETE /api/v2/stt/{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 transcripts that belong to the company your API key is issued to.

How it works

Transcription runs in the background:

Upload: Upload audio returns an attachmentId for each file, straight away.
Find the transcript: List transcripts and take the item whose attachmentId matches. Its id is the transcript’s ID.
Poll: call Get a transcript with that id every few seconds until status is completed or failed.

Upload returns file IDs (attachmentId), but Get and Delete need the transcript ID (id). Passing an attachmentId to Get returns 404. Find the transcript’s id with List transcripts first. Regenerate is the one endpoint that accepts either.

Short clips usually finish within a few seconds; allow longer for long recordings.

Transcript fields

Field	Type	Meaning
`id`	UUID	The transcript’s ID. Use it with Get, Regenerate and Delete.
`attachmentId`	UUID	The uploaded file’s ID. This is what Upload returns.
`transcript`	string	The transcript. Empty until the first transcription completes. While a regenerate is `pending`, it still holds the previous text. See Transcript format.
`status`	string	See Status values.
`failureCode`	string \| null	Why it failed, when `status` is `failed`. See Failure codes.
`targetLanguageId`	UUID \| null	The language the transcript was translated into. `null` when not translated.
`targetLanguage`	object \| null	That language’s `id`, `name` and `code`.
`attachment`	object	The uploaded file. See Attachment object.
`createdAt`	string	When the file was uploaded (ISO 8601, UTC).
`updatedAt`	string	When the transcript 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 transcribing. Poll again.
`completed`	`transcript` holds the result.
`failed`	No transcript was produced. See `failureCode`.

Failure codes

`failureCode`	Meaning
`empty_transcript`	No speech was recognised: silence, noise, or an unsupported codec. The most common cause.
`provider_error`	The transcription engine reported an error. Regenerate to retry.
`start_failed`	The job couldn’t be started. Regenerate to retry.
`transcript_fetch_failed`	The job ran but the result couldn’t be retrieved. Regenerate to retry.
`missing_transcription_id`	Internal bookkeeping error. Upload again.
`legacy_unknown`	A failure recorded before failure codes existed.

Attachment object

Field	Type	Meaning
`id`	UUID	Same as `attachmentId`.
`originalName`	string	The uploaded file’s name.
`mimeType`	string	The file’s type, for example `audio/wav`.
`fileSize`	string	Size in bytes, as a string.

Transcript format

Transcripts are speaker-labelled. Each turn starts with a label, and turns are separated by a blank line:

Speaker 1: أهلاً بيك، إزيك النهارده؟

Speaker 2: الحمد لله، كله تمام.

Numbering starts at 1.
Labels are anonymous. They tell speakers apart but carry no identity, and the same person isn’t guaranteed the same number across two uploads.
To get the turns, split on blank lines and read the Speaker N: prefix.

Translation

Set languageId when uploading or regenerating to translate the transcript. It’s a translation target, not a hint about the language being spoken; the spoken language is detected automatically.

With languageId: you get the translated text only. The original-language transcript isn’t returned alongside it.
Without it: you get the transcript in the language that was spoken.

Get language IDs from the public language list, which needs no API key:

curl "https://api-eg.olimi.ai/api/v2/languages/public?service=stt&limit=100"

Complete example

Upload a file, find its transcript, and wait for the result:

Python

import time
import requests

BASE = "https://api-eg.olimi.ai/api/v2"
HEADERS = {"X-API-KEY": "YOUR_API_KEY"}

# 1. Upload
with open("recording.wav", "rb") as f:
    up = requests.post(
        f"{BASE}/stt/upload",
        headers=HEADERS,
        files={"files": ("recording.wav", f, "audio/wav")},
        timeout=120,
    )
up.raise_for_status()
attachment_id = up.json()["data"]["attachmentIds"][0]

# 2. Find the transcript's id (newest first, so it's near the top)
listing = requests.get(
    f"{BASE}/stt", headers=HEADERS, params={"search": "recording.wav", "limit": 50}
).json()["data"]
transcript_id = next(t["id"] for t in listing if t["attachmentId"] == attachment_id)

# 3. Poll until it's done
deadline = time.time() + 300
while time.time() < deadline:
    record = requests.get(f"{BASE}/stt/{transcript_id}", headers=HEADERS).json()["data"]
    if record["status"] == "completed":
        print(record["transcript"])
        break
    if record["status"] == "failed":
        raise RuntimeError(f"transcription failed: {record['failureCode']}")
    time.sleep(5)
else:
    raise TimeoutError("transcription didn't finish in time")

Errors

Always branch on statusCode first. Errors from this API come in three shapes:

With an errorCode, like 404 stt_record_not_found: { "statusCode", "errorCode", "message" }.
Upload and Regenerate 400s: { "statusCode": 400, "message": "…", "error": "Bad Request" }. There’s no errorCode; the message says what went wrong. The exception is a languageId that isn’t a valid UUID, which returns 400 failed_update_data.
Validation (422): message is a list of what went wrong.

Status	`errorCode` or `message`	When
`400`	`No audio files provided`	Upload only. The request had no file part.
`400`	`Unexpected field - …`	Upload only. The field name isn’t `files` (it’s plural), or you sent more than 10 files.
`400`	`Target language not found`	`languageId` is a valid UUID but no such language exists.
`400`	`STT record or Attachment not found`	Regenerate only. No transcript or file with that `id` belongs to your company.
`400`	varies	Upload or Regenerate. Transcription couldn’t be started. Try again later.
`400`	`Validation failed (uuid is expected)`	The `id` in the URL isn’t a valid UUID.
`401`	`unauthenticated`	The `X-API-KEY` header is missing or the key isn’t valid.
`404`	`stt_record_not_found`	Get and Delete only. No transcript with that `id` belongs to your company. Check you’re using the transcript’s `id`, not the `attachmentId`.
`413`	none	Upload only. A file is larger than 100 MB.

The message text is for humans and may change, so prefer errorCode wherever there is one.

Getting Started

API Overview

Agents & Campaigns

Speech

Authentication

How it works

Transcript fields

Status values

Failure codes

Attachment object

Transcript format

Translation

Complete example

Errors

​Authentication

​How it works

​Transcript fields

​Status values

​Failure codes

​Attachment object

​Transcript format

​Translation

​Complete example

​Errors

Authentication

How it works

Transcript fields

Status values

Failure codes

Attachment object

Transcript format

Translation

Complete example

Errors