Kolimina Narration API
Hebrew narration from your own systems, through the same pipeline as kolimina.com: the same dictionary, pronunciation store and voices. Every narration is a project with revisions - one master file and one file per sentence - and you can correct a single sentence without generating everything again.
- Base URL:
https://kolimina.com/api/public/v1 - Authentication: an API key from the dashboard (מפתחים / API), as a Bearer token. Server-side only.
- Asynchronous: writes answer 202 with a job; poll it or receive a webhook.
Quickstart
- Create a key in the dashboard and store it as KOLIMINA_API_KEY on your server.
- Pick a voice: GET /voices.
- POST /narrations, poll the job, download the revision.
cURL
# 1. Create a narration (202 + a job)
curl -s -X POST "https://kolimina.com/api/public/v1/narrations" \
-H "Authorization: Bearer $KOLIMINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001-narration" \
-d '{"voice_id": "voice_…", "text": "שלום וברוכים הבאים. זו הקריינות הראשונה שלנו דרך ה-API."}'
# 2. Poll the job every 2–5 s (honour Retry-After) until "succeeded"
curl -s "https://kolimina.com/api/public/v1/jobs/job_…" -H "Authorization: Bearer $KOLIMINA_API_KEY"
# 3. The revision: the master file and one file per sentence
curl -s "https://kolimina.com/api/public/v1/narrations/nar_…/revisions/1" -H "Authorization: Bearer $KOLIMINA_API_KEY"
curl -s -o narration.mp3 "https://kolimina.com/api/public/v1/narrations/nar_…/revisions/1/audio" -H "Authorization: Bearer $KOLIMINA_API_KEY"
# 4. Correct one sentence (only it is re-voiced and charged; the master is rebuilt)
curl -s -X PATCH "https://kolimina.com/api/public/v1/narrations/nar_…/sentences/sent_…" \
-H "Authorization: Bearer $KOLIMINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001-fix-1" \
-d '{"base_revision": 1, "text": "זו הקריינות הראשונה שלנו."}'Guides
- Your first narrationCreate an API key, send Hebrew text, poll the job and download the audio.
- Choosing a voiceList the voices your plan includes, hear their samples, and read each voice's styles and capabilities.
- Expressions and niqqudInline expressions - the website's Hebrew markers and audio tags such as [whispers] - what is refused, and how your niqqud is kept.
- Automatic splitting or your own sentencesSend text and let Kolimina split it, or send sentences[] to keep your own editing units.
- Polling and webhooksFollow a job by polling, or receive signed webhook events.
- Downloading the master and every sentenceRead a revision's manifest and download the master file and each sentence, or hand out a temporary link.
- Correcting a sentence and replacing the masterFix one sentence: only it is re-voiced and charged, and a new revision with a new master is published.
- Accounts and costsWho can use the API, how credits are charged, and the budgets and limits that apply.
- IdempotencyRetry safely: the same Idempotency-Key never creates a second job or a second charge.
- TroubleshootingThe error envelope, request ids, and what each common error code means.
- Deletion and retentionWhat deleting a narration does, and how long revisions and files are kept.
The full contract: API reference (also as OpenAPI 3.1).
