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

האינטגרציה הראשונה

אימות, יצירת קריינות, בדיקת הסטטוס והורדת השמע - מהמפתח הראשון ועד קובץ מוכן.

כל הבקשות נשלחות לכתובת הבסיס https://kolimina.com/api/public/v1 ומחזירות JSON. העבודה אסינכרונית: יוצרים קריינות, מקבלים עבודה (job), בודקים אותה עד שהיא מסתיימת ומורידים את הקבצים.

1. אימות

יוצרים מפתח בלוח הבקרה, בלשונית מפתחים / API ← מפתחות API. מפתח חדש מקבל כברירת מחדל את כל ההרשאות שהמדריך הזה צריך. הסוד מוצג פעם אחת בלבד: שמרו אותו בשרת שלכם, במשתנה סביבה כמו KOLIMINA_API_KEY, ולעולם לא בקוד שרץ בדפדפן או באפליקציה.

כל בקשה שולחת את המפתח בכותרת Authorization, בצורה Bearer kol_live_…. כדי לבדוק שהמפתח עובד, שלחו GET /me: התשובה מציגה את החשבון, את הקרדיטים, את ההרשאות של המפתח ואת המגבלות שחלות עליכם. מפתח חסר, שגוי, שפג תוקפו או שבוטל מקבל 401 עם הקוד invalid_api_key.

cURL
curl -s "https://kolimina.com/api/public/v1/me" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY"

2. יצירת קריינות

קודם בוחרים קול: GET /voices מחזיר את הקולות שהחשבון שלכם יכול להשתמש בהם, עם קישור לדוגמת שמע. העתיקו את ה-voice_id של הקול שבחרתם - הוא לא משתנה. אפשר להעתיק אותו גם מלוח הבקרה, בלשונית מפתחים / API ← תיעוד ודוגמאות.

אחר כך שולחים POST /narrations עם voice_id ועם הטקסט בשדה text. הטקסט מחולק למשפטים בדיוק כמו באתר. בכל בקשת יצירה חובה לשלוח גם כותרת Idempotency-Key עם מזהה שאתם בוחרים לפעולה: אם התשובה אבדה ושלחתם שוב עם אותו מזהה ואותו גוף, תקבלו את אותה תשובה - בלי עבודה שנייה ובלי חיוב נוסף.

התשובה היא 202 Accepted: הקריינות נוצרה והעבודה נכנסה לתור. שמרו את narration_id ואת job_id. החיוב הוא קרדיט אחד לכל תו בטקסט, ועבודה שנכשלה או בוטלה אינה מחויבת.

cURL
curl -s "https://kolimina.com/api/public/v1/voices" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY"
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_…"}

3. בדיקת הסטטוס

בודקים את העבודה ב-GET /jobs/{job_id} כל 2–5 שניות, ומחכים לפי הכותרת Retry-After כשהיא מופיעה. במקום לבדוק שוב ושוב אפשר גם לקבל Webhook כשהעבודה מסתיימת: מוסיפים נקודת קצה בלשונית מפתחים / API ← Webhooks.

התשובה היא תמיד 200, גם כשהעבודה נכשלה. המצב נמצא בשדה status:

  • queued או processing - העבודה עדיין רצה. בודקים שוב.
  • succeeded - הגרסה מוכנה: result.revision הוא מספר הגרסה, ו-result.revision_path הוא הנתיב שלה.
  • failed או canceled - העבודה הסתיימה בלי קובץ, והסיבה בשדה error.code. עבודה כזו אינה מחויבת.
cURL
curl -s "https://kolimina.com/api/public/v1/jobs/job_…" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY"

4. הורדת השמע

כשהעבודה הצליחה, GET /narrations/{narration_id}/revisions/{revision} מחזיר את קובצי הגרסה: בשדה audio הקובץ המלא, וב-sentences כל משפט עם התזמון שלו (start_ms, end_ms, gap_after_ms) ועם audio משלו. בכל audio יש download_path - הנתיב להורדה - ו-asset_id.

מורידים עם אותו מפתח. ההורדות תומכות ב-Range וב-ETag, והקבצים של גרסה לעולם לא משתנים: תיקון של משפט יוצר גרסה חדשה.

צריכים קישור לנגן או ללקוח, בלי מפתח? POST /assets/{asset_id}/download-links מחזיר כתובת שעובדת בלי מפתח עד url_expires_at (ברירת המחדל: 15 דקות).

cURL
curl -s "https://kolimina.com/api/public/v1/narrations/nar_…/revisions/1" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY"
cURL
curl -s -o master.mp3 "https://kolimina.com/api/public/v1/narrations/nar_…/revisions/1/audio" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY"
cURL
curl -s -o s1.mp3 "https://kolimina.com/api/public/v1/narrations/nar_…/revisions/1/sentences/sent_…/audio" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY"
cURL
curl -s -X POST "https://kolimina.com/api/public/v1/assets/asset_…/download-links" \
  -H "Authorization: Bearer $KOLIMINA_API_KEY"

התהליך המלא בקוד

אותם צעדים בקוד: יצירה, המתנה לעבודה, הורדת הקובץ המלא וכל המשפטים, ותיקון משפט אחד. הקוד זהה לגרסה באנגלית: הגדירו את KOLIMINA_API_KEY והחליפו את voice_… במזהה הקול שלכם.

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

מה הלאה