Arabic speech-to-text API guide

API base URL: https://kalemio.app. Use a live API key from your account.

Download OpenAPI JSON View the raw document

Authentication

Create a key in the API console, choose only the permissions that integration needs, then send it in the Authorization header. Use environment variables on your server.

Set these variables in your terminal before running the examples. Replace the key placeholder with your live key; keep it out of source control, browser code and shared shell history.

export KALEMIO_API_BASE='https://kalemio.app'
export KALEMIO_API_KEY='YOUR_LIVE_API_KEY'

curl "$KALEMIO_API_BASE/v1/account" \
  -H "Authorization: Bearer $KALEMIO_API_KEY"

Keys are shown once and cannot be recovered. Rotate a lost or exposed key in the portal; rotation revokes the old key immediately. You can see when a key was last used in the console.

Verify your key with GET /v1/account. It returns your mode, available seconds, and whether transcription is enabled. Invalid or revoked keys return 401; a key missing the required permission returns 403.

Upload audio or video

Submit one audio or video file as multipart form data. You can send video directly; we extract the audio for you. MP3, M4A, PCM WAV, MP4 and MOV files are supported up to 20 MiB and 10 minutes. The language is Arabic, including dialectal speech. Choose automatic speaker detection or set the number of speakers if you know it.

curl "$KALEMIO_API_BASE/v1/transcriptions" \
  -H "Authorization: Bearer $KALEMIO_API_KEY" \
  -H "Idempotency-Key: recording-2026-001" \
  -F 'file=@conversation.m4a' \
  -F 'language=ar' \
  -F 'speakers=auto'

A successful upload returns 202 Accepted with a job ID. Store the ID to retrieve the result later. Before running the polling example, set export JOB_ID='tr_example', replacing tr_example with the returned ID. Use a new Idempotency-Key for each different recording.

{ "id": "tr_example", "status": "queued" }

Check progress

curl "$KALEMIO_API_BASE/v1/transcriptions/$JOB_ID" \
  -H "Authorization: Bearer $KALEMIO_API_KEY"

Poll every 3–5 seconds. Jobs move from queued to running, then completed or failed.

Download results

Once complete, retrieve JSON with GET /v1/transcriptions/{id}/result or subtitles with GET /v1/transcriptions/{id}/srt. Authenticate both requests.

{ "text": "مرحبا", "words": [
  { "text": "مرحبا", "start": 1.24,
    "end": 1.78, "speaker_id": "speaker_0" }
] }

Work with word-level timestamps

Each word has a start and end time in seconds from the beginning of the recording. In the example above, مرحبا starts at 1.24 seconds and ends at 1.78 seconds.

text

The transcribed word, with the dialect wording preserved.

start / end

The word’s time range in seconds. Use it to sync captions or seek to a passage.

speaker_id

A label for the voice within this recording, such as speaker_0. It does not identify the same person across recordings.

For word highlighting, show the word while playback is between its start and end times. For custom subtitles, group adjacent words into readable lines and use the first word’s start and last word’s end. Use the SRT download if you want ready-made subtitle cues.

These examples illustrate the response format. Dialect accuracy and word-timing benchmarks are coming soon.

Errors and limits

Uploads are limited to 20 MiB and 10 minutes, with two active jobs per account. Prepaid credit accounts are billed by uploaded media duration rounded up to the next second, reserve minutes on acceptance, and receive them back if a job fails. Direct metered accounts are billed at US$0.09 per processed audio minute, rounded up to one minute, after a successful job. No automatic overages on prepaid accounts. Results are available for 24 hours from submission. Reuse an Idempotency-Key only for the same file and speaker settings; it remains associated with that job. Test keys do not process recordings.

Billing and data handling

Plans and minutes

Plans are billed monthly in USD or CAD. Included minutes reset at renewal and do not roll over. Top-up minutes never expire and are used after monthly minutes. Mid-month upgrades charge and grant minutes proportionally for the remaining billing period after successful payment. The renewal date stays the same. Cancel from the API console before renewal to stop the next charge.

Failed jobs and refunds

Failed transcription jobs return minutes to their original allowance; expired monthly minutes remain expired; a network interruption during submission can also cause a job to fail without a charge. Refunded or disputed payments remove the corresponding credits and may leave a negative balance if those credits have already been used. Contact Support email for purchase or refund help.

Your recordings and results

Audio is processed on our transcription infrastructure and hosting providers. Uploaded media is not used to train models. Working audio and upstream job files are deleted after processing; downloadable results expire 24 hours after submission. Cleanup retries during service outages. Account, payment and usage metadata remain for service/accounting. Only upload files you have permission to process. Contact support to request account deletion.