Your first narration
Create an API key, send Hebrew text, poll the job and download the audio.
Create a key in the dashboard under מפתחים / API → מפתחות API. The secret is shown once; keep it on your server (an environment variable such as KOLIMINA_API_KEY) and never in browser or mobile code.
All work is asynchronous. Creating a narration answers 202 with a job; poll the job every 2–5 seconds (honour Retry-After) or receive a webhook, then fetch the revision it produced.
cURL
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: first-narration-1" \
-d '{"voice_id": "voice_…", "text": "שלום, זו הקריינות הראשונה שלי."}'202 Accepted
{"narration_id": "nar_…", "job_id": "job_…", "status": "queued", "current_revision": null, "poll_path": "/jobs/job_…"}cURL
curl -s "https://kolimina.com/api/public/v1/jobs/job_…" \
-H "Authorization: Bearer $KOLIMINA_API_KEY"The complete workflow
Create, wait, download the master and every sentence, then correct one sentence:
Python
import os, time, uuid, requests
BASE = "https://kolimina.com/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['KOLIMINA_API_KEY']}"}
def wait(job_id):
while True:
r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
r.raise_for_status()
job = r.json()
if job["status"] in ("succeeded", "failed", "canceled"):
return job
time.sleep(int(r.headers.get("Retry-After", "3")))
def post(path, body, key, method="POST"):
# The same Idempotency-Key on every retry: a lost response never creates a second job.
for _ in range(5):
r = requests.request(method, f"{BASE}{path}", json=body, headers={**HEADERS, "Idempotency-Key": key}, timeout=30)
if r.status_code == 409 and r.json()["error"]["code"] == "idempotency_in_progress":
time.sleep(int(r.headers.get("Retry-After", "2")))
continue
r.raise_for_status()
return r.json()
raise RuntimeError("still in progress")
created = post("/narrations", {"voice_id": "voice_…", "text": "שלום וברוכים הבאים. זו הקריינות הראשונה שלנו דרך ה-API."}, f"create-{uuid.uuid4()}")
job = wait(created["job_id"])
assert job["status"] == "succeeded", job["error"]
rev = requests.get(f"{BASE}{job['result']['revision_path']}", headers=HEADERS, timeout=30).json()
with open("narration.mp3", "wb") as f:
f.write(requests.get(f"{BASE}{rev['audio']['download_path']}", headers=HEADERS, timeout=120).content)
for s in rev["sentences"]:
with open(f"sentence-{s['index']}.mp3", "wb") as f:
f.write(requests.get(f"{BASE}{s['audio']['download_path']}", headers=HEADERS, timeout=120).content)
# Correct the second sentence against the revision you have.
fix = post(f"/narrations/{rev['narration_id']}/sentences/{rev['sentences'][1]['sentence_id']}",
{"base_revision": rev["revision"], "text": "זו הקריינות הראשונה שלנו."}, f"fix-{uuid.uuid4()}", method="PATCH")
print(wait(fix["job_id"])["result"])Node.js
// Node.js 18+ (built-in fetch)
import { randomUUID } from "node:crypto";
import { writeFile } from "node:fs/promises";
const BASE = "https://kolimina.com/api/public/v1";
const auth = { Authorization: `Bearer ${process.env.KOLIMINA_API_KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function call(method, path, body, idempotencyKey) {
for (;;) {
const res = await fetch(BASE + path, {
method,
headers: { ...auth, ...(body ? { "Content-Type": "application/json" } : {}), ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}) },
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 409 || res.status === 429) {
const err = await res.clone().json();
if (err.error.code === "idempotency_in_progress" || res.status === 429) {
await sleep(Number(res.headers.get("Retry-After") ?? 2) * 1000);
continue; // the same key and body: never a second job
}
}
if (!res.ok) throw new Error(JSON.stringify(await res.json()));
return res;
}
}
async function wait(jobId) {
for (;;) {
const res = await call("GET", `/jobs/${jobId}`);
const job = await res.json();
if (["succeeded", "failed", "canceled"].includes(job.status)) return job;
await sleep(Number(res.headers.get("Retry-After") ?? 3) * 1000);
}
}
const created = await (await call("POST", "/narrations", { voice_id: "voice_…", text: "שלום וברוכים הבאים. זו הקריינות הראשונה שלנו דרך ה-API." }, randomUUID())).json();
const job = await wait(created.job_id);
if (job.status !== "succeeded") throw new Error(job.error.code);
const rev = await (await call("GET", job.result.revision_path)).json();
await writeFile("narration.mp3", Buffer.from(await (await call("GET", rev.audio.download_path)).arrayBuffer()));
for (const s of rev.sentences) {
await writeFile(`sentence-${s.index}.mp3`, Buffer.from(await (await call("GET", s.audio.download_path)).arrayBuffer()));
}