KolWrite KolWrite المطورون

البدء السريع في KolWrite API

نفّذ آليًا كل ما تفعله في تطبيق KolWrite — ارفع ملفًا وحوّله إلى نص بكامل الخيارات، ثم صدّر النص المفرّغ وشاركه — باستخدام رمز وصول شخصي (PAT).

عنوان URL الأساسي: https://api.kolwrite.com

1. أنشئ رمز وصول

في تطبيق KolWrite: الإعدادات → الحساب → الوصول إلى API → إنشاء رمز وصول. اختر النطاقات التي تحتاج إليها (يستخدم هذا الشرح files:write وjobs:write وjobs:read وtranscripts:read). لا يُعرض السر (kol_...) سوى مرة واحدة — فاحفظه بأمان.

أرسله مع كل طلب:

export KOLWRITE_TOKEN="kol_..."
curl -H "Authorization: Bearer $KOLWRITE_TOKEN" \
  https://api.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.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 كي لا تؤدي إعادة المحاولة إلى إرسال المهمة مرتين:

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. استعلم حتى الاكتمال

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. صدّر النص المفرّغ

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:

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

الخطوة التالية

نسخة Markdown من هذه الصفحة