KolWrite KolWrite מפתחים

התחלה מהירה עם KolWrite API

הפכו כל פעולה ביישום KolWrite לאוטומטית — העלאת קובץ, תמלול עם כל האפשרויות, ייצוא התמליל ושיתוף שלו — באמצעות אסימון גישה אישי (PAT).

כתובת URL בסיסית: https://api-prod.kolwrite.com

1. יצירת אסימון

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

ביישום KolWrite: הגדרות → חשבון → גישת API → יצירת אסימון. בחרו את היקפי ההרשאה הדרושים לכם (המדריך הזה משתמש ב-files:write, ב-jobs:write, ב-jobs:read וב-transcripts:read). הסוד (kol_...) מוצג פעם אחת — שמרו אותו במקום בטוח.

שלחו אותו בכל בקשה:

export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/billing/balance

2. העלאת קובץ

צרו סשן העלאה, שלחו את תוכן הקובץ בבקשת PUT לכתובת ה-URL החתומה מראש, ולאחר מכן השלימו את ההעלאה:

# a. create the session
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api-prod.kolwrite.com/api/v1/media/upload-session \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"filename\": \"interview.wav\", \"file_size_bytes\": $SIZE, \"content_type\": \"audio/wav\"}"
# → data.upload_url, data.finalize_token

# b. upload the bytes directly to storage
curl -X PUT "$UPLOAD_URL" --data-binary @interview.wav \
  -H "Content-Type: audio/wav"

# c. finalize
curl -X POST https://api-prod.kolwrite.com/api/v1/media/complete \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"finalize_token": "FINALIZE_TOKEN"}'
# → 201, data.media_id

קבצים גדולים מועלים בחלקים: הסשן מחזיר אז את data.upload_url בערך null וכתובת לכל חלק ב-data.multipart_part_urls. שלחו כל חלק בבקשת PUT, שמרו את הכותרת ETag מכל תשובה, ושלחו אותן לקריאת הסיום כ-uploaded_parts: רשימת אובייקטים מהצורה {part_number, etag}.

3. תמלול הקובץ

צרו משימה. profile בוחר את רמת המודל (oracle, oracle-mini, oracle-pro, oracle-max — אפשר להציג אותן באמצעות GET /api/v1/models); options כולל את כל מה שזמין בחלון הניתוח ביישום. השתמשו ב-Idempotency-Key כדי שניסיונות חוזרים לעולם לא ישלחו את המשימה פעמיים:

curl -X POST https://api-prod.kolwrite.com/api/v1/jobs \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: interview-2026-07-08" \
  -d '{
    "type": "transcription",
    "input": {"type": "media_ref", "media_id": "MEDIA_ID"},
    "profile": "oracle",
    "options": {
      "language": "auto",
      "target_language": null,
      "diarization": {"mode": "regular", "num_speakers": null, "auto_speaker_names": true}
    }
  }'
# → 202 Accepted, data.job_id, data.status = "queued"

צריבת כתוביות פועלת באותו אופן עם "type": "caption_burn" ובלוק סגנון options.caption_burn — לפרטים, ראו במפרט.

4. בדיקת מצב עד להשלמה

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID
# data.status: queued → running → succeeded | failed | cancelled
# data.progress: 0–100, plus queue position while waiting

5. ייצוא התמליל

curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  "https://api-prod.kolwrite.com/api/v1/jobs/JOB_ID/export?format=srt&include_speakers=true"

פורמטים: text, json, srt, vtt, docx, pdf. הייצוא הוא התמליל כפי שהוא עכשיו: תיקונים שאנשים עושים בעורך של KolWrite נכללים מייד כשהם נשמרים, בלי צעד נוסף.

כדי לקרוא את התמליל הנוכחי של קובץ לפי מזהה קובץ סביבת העבודה שלו (אותו טקסט שאנשים רואים באפליקציה), השתמשו ב-GET /api/v1/workspace-files/WORKSPACE_FILE_ID/transcript?format=json עם היקף ההרשאה transcripts:read. הכותרות X-Transcript-Version-Id ו-X-Transcript-Revision משתנות בכל פעם שהתמליל משתנה, כך שסקריפט שבודק מעת לעת יודע מתי יש משהו חדש. גרסאות תמליל שמורות נמצאות תחת GET /api/v1/jobs/JOB_ID/artifacts ו-GET /api/v1/artifacts/{artifact_id}; גרסה שמורה היא תמונת מצב קבועה ואינה כוללת עריכות מאוחרות יותר.

כדי לקבל רק תמלילים שאדם אישר, בקשו מהבודקים ללחוץ על "סמן כנבדק" בעורך. מאז קריאת התמליל מחזירה X-Transcript-Review-Status: reviewed עד העריכה הבאה, ו-require_reviewed=true גורם לה להחזיר 409 transcript_not_reviewed בכל מצב אחר. GET /api/v1/transcript-reviews?since=... מציג קבצים שנבדקו מאז הבדיקה הקודמת שלכם. או בלי בדיקות חוזרות: הוסיפו webhook עם POST /api/v1/webhook-endpoints (היקף webhooks:manage) עבור transcript.reviewed, job.completed, job.failed, upload.completed או upload.failed, ואמתו בכל בקשה את הכותרת KolWrite-Signature (HMAC-SHA256 של <t>.<raw body> עם הסוד של נקודת הקצה).

הורדת SRT ו-VTT חינמית בכל מסלול.

6. אופציונלי: שיתוף התמליל

עם shares:write:

curl -X POST https://api-prod.kolwrite.com/api/v1/shares \
  -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"share_kind": "transcript", "artifact_id": "ARTIFACT_ID", "access_scope": "everyone"}'
# → data.share_url

להמשך

גרסת Markdown של העמוד