# البدء السريع في 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` وعنوان URL لكل جزء في `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/ar/authentication.md)
- [الأخطاء وحدود معدل الطلبات](/locales/ar/errors.md)
- [مرجع API الكامل](/) · [مواصفات OpenAPI](/openapi.json)