البدء السريع في 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 وعنوان 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-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