דלג לתוכן הראשי
Kolimina - עברית שנשמעת נכון

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()));
}