תיעוד ה-API של KolWrite

אימות

יש לאמת כל בקשת API באמצעות מפתח ה-API הייחודי שלכם. יש לכלול אותו בכותרות הבקשה:

x-api-key: YOUR_API_KEY

אפשר ליצור ולנהל את מפתחות ה-API שלכם במקטע מסוף KolWrite לאחר יצירת חשבון.

התחלה מהירה

התחילו במהירות בעזרת הדוגמאות הבסיסיות האלה.

1. התחלת התמלול

שלחו בקשת POST לנקודת הקצה `/transcribe` עם כתובת ה-URL של קובץ האודיו שברצונכם לתמלל.

בקשה:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

תגובה:

ה-API מחזיר `jobId` שישמש אתכם לאחזור תוצאות התמלול.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. קבלת תוצאת התמלול

מ־Send a GET request עד the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

בקשה:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

תגובה (דוגמה):

לאחר שסטטוס המשימה הוא COMPLETED, התגובה תכלול את פרטי התמלול.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

מודלים ויחידות שימוש

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

יחידת שימוש אחת היא יחידת החיוב של ה-API, שהוצגה בעבר כ-$1.00 במסוף ה-API.

חשבונות חיוב ישראליים זכאים רוכשים יחידות שימוש ב-ILS במחיר נטו של ILS 3.60 ליחידה, לפני מע״מ. לפני התשלום יוצגו יחידות השימוש, הסכום נטו, המע״מ והסכום הסופי ב-ILS. חשבונות אחרים רוכשים יחידות שימוש ב-USD במחיר של USD 1.20 ליחידה, אלא אם חלים תנאי הזמנה נפרדים.

תוספים: הפרדת דוברים רגילה ו- standard הפרדה לפי ערוצים כלולות. הפרדת דוברים Pro מוסיפה 0.20 יחידות שימוש לכל שעת אודיו. overlap הפרדת ערוצים מחויבת בתעריף הדגם שנבחר לפי הגבוה מבין משך ההקלטה או סך זמן הדיבור שזוהה בכל ערוציה הפיזיים; לאף מצב ערוצים אין תוספת תשלום עבור דיאריזציה. Oracle Mini מפעיל אוטומטית יישור חותמות זמן כאשר נבחרת דיאריזציה או הפרדת ערוצים.

נקודות קצה של ה-API

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

שולח קובץ אודיו לתמלול אסינכרוני עם הפרדת דוברים אופציונלית.

פרמטרים בגוף הבקשה

בקשה לדוגמה (עם הפרדת דוברים):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

תגובה:

מחזיר אובייקט שמכיל את ה-`jobId` של משימת התמלול שנשלחה.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

מאחזר את הסטטוס ואת התוצאה של משימת תמלול מסוימת.

פרמטרים של הנתיב

גוף התגובה

תגובה לדוגמה (פלט JSON עם הפרדת דוברים):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

הפרדת דוברים

הפרדת דוברים היא תהליך של זיהוי והפרדה בין דוברים שונים בהקלטת אודיו. כשהאפשרות מופעלת, KolWrite מנתחת את האודיו, מזהה חילופי דוברים ומסמנת כל מקטע בהתאם.

דיאריזציית דוברים והפרדת ערוצים זמינות בכל הדגמים המופיעים. Oracle Mini מפעיל אוטומטית יישור חותמות זמן בכל בחירה של מצב דוברים.

איך מפעילים הפרדת דוברים

כדי להפעיל הפרדת דוברים, הגדירו את include_diarization הפרמטר לערך true בבקשת התמלול שלכם:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

מיטוב מספר הדוברים

לקבלת התוצאות הטובות ביותר, ציינו את מספר הדוברים הצפוי באמצעות num_speakers הפרמטר. אם אינכם יודעים את המספר המדויק, תוכלו:

• השמיטו את הפרמטר (המערכת תזהה אוטומטית)
• הגדירו טווח משוער לפי ההערכה הטובה ביותר שלכם

הפרדת דוברים Pro

לדיוק גבוה יותר בזיהוי דוברים, במיוחד בתנאים אקוסטיים מאתגרים, אפשר להפעיל הפרדת דוברים Pro. תכונה זו כרוכה בתוספת של 0.20 יחידות שימוש לכל שעת אודיו.

כדי להשתמש בו, הגדירו את pro_diarization הפרמטר לערך true. ניתן להשתמש בפרמטר זה יחד עם include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

הפרדת דוברים לפי ערוצים

הפרדה לפי ערוצים מתמללת כל ערוץ אודיו פיזי בנפרד ומסמנת את המקטעים והמילים המוחזרים בשדות הפיזיים channel ו- speaker. נדרש מקור בעל שניים עד שמונה ערוצים שיצוין בפרמטר audio_url ואי אפשר לשלבו עם דיאריזציה רגילה או Pro. Oracle Mini מפעיל אוטומטית יישור חותמות זמן לכל אחד ממצבי הערוצים.

שימוש standard כאשר הדוברים מדברים בתורם; החיוב הוא פעם אחת לפי תעריף האודיו של המודל שנבחר. השתמשו ב- overlap כאשר דוברים עשויים לדבר במקביל; החיוב הוא לפי תעריף המודל שנבחר, לפי הגבוה מבין משך ההקלטה או סך זמן הדיבור שזוהה בכל ערוציה הפיזיים.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

Webhooks לסיום

הגדרה webhook_url כדי לקבל transcription.completed ו- transcription.failed אירועים. במקרה של כשל במסירה מתבצעים ניסיונות חוזרים, אך הלקוחות צריכים להמשיך לתמוך ב- GET /transcribe/{jobId} כמקור המידע הקובע.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

כל מסירה כוללת X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id, וכן X-KolWrite-Timestamp. המסירה מתבצעת לפחות פעם אחת; ניסיונות חוזרים משתמשים באותו מזהה מסירה, לכן יש להסיר אירועים כפולים באמצעות X-KolWrite-Delivery-Id. כאשר מוגדר סוד, חשבו HMAC-SHA256 על timestamp + "." + raw_request_body ולהשוות מול X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

עבור output_format: "json", ה-webhook result השדה הוא אובייקט JSON. תוצאות TXT ו-SRT נמסרות כמחרוזות.

בתוצאות גדולות עשוי להופיע result_omitted עד true; את התוצאה המלאה יש למשוך מ- GET /transcribe/{jobId}. אירועים שנכשלו כוללים שדה error שדה.

פורמט פלט עם הפרדת דוברים

כשהפרדת דוברים מופעלת, כל מקטע בפלט JSON יכלול speaker שדה שמזהה את הדובר (למשל "דובר 1", "דובר 2" וכן הלאה).

פורמטי פלט

פורמט JSON

פלט מפורט עם מקטעים, חותמות זמן ונתונים אופציונליים ברמת המילה.

פורמט TXT

תמלול בטקסט פשוט עם תוויות דוברים (כאשר הפרדת דוברים מופעלת).

פורמט SRT

פורמט כתוביות SubRip עם חותמות זמן, התואם לנגני וידאו ולעורכי כתוביות.

מצב השירות

עיינו ב- דף הסטטוס של KolWrite API לקבלת זמינות בזמן אמת, היסטוריית זמן פעילות ותקריות ברמת השירות.

GET /health אינו דורש מפתח API ומחזיר את המצב הנוכחי של ה-API, קליטת המשימות ועיבוד התמלול. תגובת 200 פירושה שהשירות פעיל או פועל באופן חלקי; תגובת 503 פירושה שהמצב הנוכחי אינו ידוע או אינו זמין. שתי התגובות כוללות פרטי סטטוס בפורמט JSON.

GET /health/history?period=24h מחזיר היסטוריית זמינות תמציתית. התקופות הנתמכות הן 24h, 7d, וכן 30d.

קודי סטטוס