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

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

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

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

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

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

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

## 2. העלאת קובץ

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

```bash
# a. create the session
SIZE=$(wc -c interview.wav | awk '{print $1}')
curl -X POST https://api.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.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`
כדי שניסיונות חוזרים לעולם לא ישלחו את המשימה פעמיים:

```bash
curl -X POST https://api.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. בדיקת מצב עד להשלמה

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

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

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

פורמטים: `text`, `json`, `srt`, `vtt`. תוצרי תמליל שנשמרים לאורך זמן (עם
היסטוריית גרסאות) זמינים דרך `GET /api/v1/jobs/JOB_ID/artifacts` ו-
`GET /api/v1/artifacts/{artifact_id}` עם היקף ההרשאה `transcripts:read`.

הורדת SRT ו-VTT דורשת מסלול Plus ומעלה; מסלולים אחרים מקבלים HTTP 403 עם הקוד `subtitle_export_requires_plus`.

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

עם `shares:write`:

```bash
curl -X POST https://api.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
```

## להמשך

- [אימות והיקפי הרשאה](/locales/he/authentication.md)
- [שגיאות ומגבלות קצב בקשות](/locales/he/errors.md)
- [מפרט API מלא](/) · [מפרט OpenAPI](/openapi.json)