האינטגרציה הראשונה
אימות, יצירת קריינות, בדיקת הסטטוס והורדת השמע - מהמפתח הראשון ועד קובץ מוכן.
כל הבקשות נשלחות לכתובת הבסיס 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 -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 -s "https://kolimina.com/api/public/v1/voices" \
-H "Authorization: Bearer $KOLIMINA_API_KEY"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": "שלום, זו הקריינות הראשונה שלי."}'{"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 -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 -s "https://kolimina.com/api/public/v1/narrations/nar_…/revisions/1" \
-H "Authorization: Bearer $KOLIMINA_API_KEY"curl -s -o master.mp3 "https://kolimina.com/api/public/v1/narrations/nar_…/revisions/1/audio" \
-H "Authorization: Bearer $KOLIMINA_API_KEY"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 -s -X POST "https://kolimina.com/api/public/v1/assets/asset_…/download-links" \
-H "Authorization: Bearer $KOLIMINA_API_KEY"התהליך המלא בקוד
אותם צעדים בקוד: יצירה, המתנה לעבודה, הורדת הקובץ המלא וכל המשפטים, ותיקון משפט אחד. הקוד זהה לגרסה באנגלית: הגדירו את KOLIMINA_API_KEY והחליפו את voice_… במזהה הקול שלכם.
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 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()));
}מה הלאה
- תיקון משפט והחלפת הקובץ המלא (באנגלית)
- פיצול אוטומטי או משפטים משלכם, ותצוגה מקדימה (באנגלית)
- Webhooks ואימות החתימה (באנגלית)
- Idempotency ושליחה חוזרת בטוחה (באנגלית)
- קודי שגיאה ופתרון תקלות (באנגלית)
