תמלול לאפליקציות ולמוצרי SaaS

הזרימה בפרודקשן

1. השרת שלכם קורא ל־POST /upload עבור הקובץ של המשתמש ומחזיר ללקוח את הטופס החתום, או מעלה אותו בעצמו (עד 100 MiB).
2. פותחים משימה עם ה־fileUrl שחזר בתור audio_url ועם ה־webhook_url שלכם.
3. מאמתים את חתימת ה־webhook, מסננים כפילויות לפי X-KolWrite-Delivery-Id, וקוראים ל־GET /transcribe/{jobId} אם result_omitted הוא true.
4. שומרים את ה־segments (טקסט, זמנים, דוברים) ומציגים אותם; מייצאים srt או txt לפי הצורך.

בקשת המשימה:

{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}

אימות webhooks

import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

כל משלוח מגיע לפחות פעם אחת, ונשלח שוב אם נכשל. GET /transcribe/{jobId} נשאר מקור האמת.

בחירת מודל לכל משימה

מגבלות שכדאי לתכנן סביבן

• העלאה ב־Base64 בתוך הבקשה: עד 4 MiB של מדיה. העלאה חתומה: עד 100 MiB.
• הטופס החתום פג אחרי 60 דקות; כתובת הקריאה אחרי 24 שעות.
• המשימות אסינכרוניות: הציגו התקדמות לפי PENDING ו־IN_PROGRESS.
• אי אפשר לשלב channel_speaker_separation עם זיהוי דוברים.

שאלות ותשובות