وثائق KolWrite API

المصادقة

يجب مصادقة جميع طلبات API باستخدام مفتاح API الفريد الخاص بك. أدرجه في ترويسات الطلب:

x-api-key: YOUR_API_KEY

يمكنك إنشاء مفاتيح API وإدارتها من صفحة وحدة تحكم KolWrite بعد إنشاء حساب.

البدء السريع

ابدأ بسرعة باستخدام هذه الأمثلة الأساسية.

1. بدء التفريغ النصي

أرسل طلب POST إلى نقطة النهاية `/transcribe` مع عنوان URL لملف الصوت الذي تريد تفريغه نصيًا.

الطلب:

POST https://app.kolwrite.com/transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270"
}

الاستجابة:

تعيد API قيمة `jobId` ستستخدمها لاسترداد نتائج التفريغ النصي.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

2. الحصول على نتيجة التفريغ النصي

من Send a GET request إلى the `/transcribe/{jobId}` endpoint using the `jobId` received from the previous step.

الطلب:

GET https://app.kolwrite.com/transcribe/34c63d45-4cb5-473b-bc60-25c175e69c57
x-api-key: YOUR_API_KEY

الاستجابة (مثال):

عندما تصبح حالة المهمة COMPLETED، وستتضمن الاستجابة تفاصيل التفريغ النصي.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          },
          {
            "start": 1.5,
            "end": 1.9,
            "word": "welcome"
          }
        ]
      }
    ]
  }
}

النماذج ووحدات الاستخدام

يُقاس استخدام النموذج بوحدات استخدام لكل ثانية دون حد أدنى للرسوم. وتعرض عملية الدفع والإيصالات والمستندات الضريبية عملة الدفع الفعلية المستخدمة للشراء.

وحدة استخدام واحدة هي وحدة فوترة API التي كانت معروضة سابقًا بسعر $1.00 في وحدة تحكم API.

تشتري حسابات الفوترة الإسرائيلية المؤهلة وحدات الاستخدام بعملة ILS بسعر صافٍ قدره ILS 3.60 لكل وحدة استخدام قبل ضريبة القيمة المضافة. تعرض عملية الدفع وحدات الاستخدام والمبلغ الصافي وضريبة القيمة المضافة والإجمالي النهائي بعملة ILS قبل الدفع. وتشتري الحسابات الأخرى وحدات الاستخدام بعملة USD بسعر USD 1.20 لكل وحدة استخدام، ما لم تنطبق شروط طلب منفصلة.

الإضافات: يشمل السعر الفصل العادي بين المتحدثين وفصل القنوات بوضع standard المشمول أيضًا. ويضيف الفصل Pro بين المتحدثين 0.20 وحدة استخدام لكل ساعة صوتية. overlap تتم فوترة فصل القنوات بسعر النموذج المحدد للأكبر من مدة التسجيل أو مجموع زمن الكلام المكتشف في قنواته الفعلية؛ ولا يضيف أي من وضعي القنوات رسوما إضافية لتجزئة المتحدثين. يفعّل Oracle Mini محاذاة الطوابع الزمنية تلقائيا عند اختيار تجزئة المتحدثين أو فصل القنوات.

نقاط نهاية API

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "clip.mp3",
  "contentType": "audio/mpeg",
  "content": "<base64-encoded media bytes>"
}

POST /upload
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "filename": "meeting.mp3",
  "contentType": "audio/mpeg"
}

// upload is the JSON response from POST /upload
const form = new FormData();
for (const [name, value] of Object.entries(upload.uploadFields)) {
  form.append(name, value);
}
form.append('file', file, file.name);
await fetch(upload.uploadUrl, { method: 'POST', body: form });

POST /transcribe
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "audio_url": "<fileUrl returned by POST /upload>",
  "model": "oracle"
}

POST /transcribe

يرسل ملفًا صوتيًا لتفريغه نصيًا بصورة غير متزامنة مع فصل اختياري للمتحدثين.

معاملات نص الطلب

مثال على طلب (مع فصل المتحدثين):

{
  "audio_url": "https://salford.figshare.com/ndownloader/files/14630270",
  "word_timestamps": true,
  "model": "edge",
  "output_format": "json",
  "include_diarization": true,
  "num_speakers": 2
}

الاستجابة:

يعيد كائنًا يحتوي على `jobId` لمهمة التفريغ النصي المرسلة.

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57"
}

GET /transcribe/{jobId}

يسترد حالة مهمة تفريغ نصي محددة ونتيجتها.

معاملات المسار

نص الاستجابة

مثال على استجابة (مخرجات JSON مع فصل المتحدثين):

{
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "result": {
    "language": "en",
    "segments": [
      {
        "start": 0.5,
        "end": 3.2,
        "text": "Hello everyone, welcome to today's meeting.",
        "speaker": "Speaker 1",
        "words": [
          {
            "start": 0.5,
            "end": 0.8,
            "word": "Hello"
          },
          {
            "start": 0.9,
            "end": 1.4,
            "word": "everyone"
          }
        ]
      },
      {
        "start": 4.1,
        "end": 6.8,
        "text": "Thank you. Let's begin with the quarterly review.",
        "speaker": "Speaker 2",
        "words": [
          {
            "start": 4.1,
            "end": 4.5,
            "word": "Thank"
          },
          {
            "start": 4.6,
            "end": 4.9,
            "word": "you"
          }
        ]
      }
    ]
  }
}

فصل المتحدثين

فصل المتحدثين هو عملية تحديد المتحدثين المختلفين في تسجيل صوتي والفصل بينهم. وعند تفعيله، تحلل KolWrite الصوت لاكتشاف تبدّل المتحدثين وتسمية كل مقطع وفقًا لذلك.

تتوفر تجزئة المتحدثين وفصل القنوات مع كل النماذج المدرجة. يفعّل Oracle Mini محاذاة الطوابع الزمنية تلقائيا كلما تم اختيار وضع متحدثين.

كيفية تفعيل فصل المتحدثين

لتفعيل فصل المتحدثين، اضبط المعامل include_diarization على true في طلب التفريغ النصي:

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "include_diarization": true,
  "num_speakers": 3
}

تحسين عدد المتحدثين

للحصول على أفضل النتائج، حدد العدد المتوقع للمتحدثين باستخدام المعامل num_speakers وفي حال عدم معرفة العدد الدقيق، يمكنك:

• احذف المعامل (سيكتشف النظام تلقائيًا)
• قدّم نطاقًا تقديريًا بضبطه على أفضل تقدير لديك

الفصل Pro بين المتحدثين

للحصول على دقة أعلى في تحديد المتحدثين، لا سيما في الظروف الصوتية الصعبة، يمكنك تفعيل الفصل Pro بين المتحدثين. تكلف هذه الميزة تكلفة إضافية قدرها 0.20 وحدة استخدام لكل ساعة صوتية.

لاستخدامه، اضبط المعامل pro_diarization على true. يمكن استخدام هذا المعامل مع include_diarization.

{
  "audio_url": "https://example.com/panel-discussion.mp3",
  "include_diarization": true,
  "pro_diarization": true
}

فصل المتحدثين حسب القنوات

يفرّغ فصل القنوات كل مسار صوتي مادي بصورة مستقلة ويسِم المقاطع والكلمات المعادة بحقول المسار المادية channel و speaker. يلزم مصدر من قناتين إلى ثماني قنوات محدد عبر audio_url ولا يمكن دمجه مع تجزئة المتحدثين العادية أو Pro. يفعّل Oracle Mini محاذاة الطوابع الزمنية تلقائيا لأي من وضعي القنوات.

استخدم standard عندما يتناوب المتحدثون على الكلام؛ ويُحاسب بسعر صوت واحد للنموذج المحدد. استخدم overlap عندما قد يتداخل كلام المتحدثين؛ ويُحاسب بسعر النموذج المحدد للأكبر من مدة التسجيل أو مجموع زمن الكلام المكتشف في قنواته الفعلية.

{
  "audio_url": "https://example.com/stereo-call.wav",
  "model": "oracle",
  "channel_speaker_separation": "overlap",
  "channel_labels": {"0": "Agent", "1": "Customer"}
}

إخطارات webhook عند الاكتمال

اضبط webhook_url لتلقّي الحدثين transcription.completed و transcription.failed وتُعاد محاولة عمليات التسليم الفاشلة، لكن ينبغي للعملاء الاستمرار في دعم GET /transcribe/{jobId} بوصفه المرجع المعتمد.

{
  "audio_url": "https://example.com/meeting-audio.mp3",
  "output_format": "json",
  "webhook_url": "https://example.com/kolwrite-webhook",
  "webhook_secret": "replace-with-your-secret"
}

تتضمن كل عملية تسليم X-KolWrite-Event, X-KolWrite-Job-Id, X-KolWrite-Delivery-Id، و X-KolWrite-Timestamp. يتم التسليم مرة واحدة على الأقل؛ وتستخدم المحاولات المتكررة معرّف التسليم نفسه، لذا أزِل تكرار الأحداث باستخدام X-KolWrite-Delivery-Id. عند تكوين سر، احسب HMAC-SHA256 على timestamp + "." + raw_request_body وقارنه بـ X-KolWrite-Signature.

{
  "event": "transcription.completed",
  "jobId": "34c63d45-4cb5-473b-bc60-25c175e69c57",
  "status": "COMPLETED",
  "createdAt": "2026-07-10T09:30:00+00:00",
  "model": "base",
  "output_format": "json",
  "result_available": true,
  "result_omitted": false,
  "result_size_bytes": 12480,
  "result": { "language": "en", "segments": [] }
}

عندما تكون القيمة output_format: "json"، يكون حقل webhook المسمى result كائن JSON. وتُسلَّم نتائج TXT وSRT كسلاسل نصية.

قد تضبط النتائج الكبيرة الحقل result_omitted على true؛ واجلب النتيجة الكاملة من GET /transcribe/{jobId}. تتضمن الأحداث الفاشلة حقل error .

تنسيق المخرجات مع فصل المتحدثين

عند تفعيل فصل المتحدثين، سيتضمن كل مقطع في مخرجات JSON حقل speaker يحدد المتحدث (مثل "Speaker 1" و"Speaker 2" وما إلى ذلك).

تنسيقات المخرجات

تنسيق JSON

مخرجات مفصلة تتضمن المقاطع والطوابع الزمنية وبيانات اختيارية على مستوى الكلمات.

تنسيق TXT

تفريغ بنص عادي مع تسميات المتحدثين (عند تفعيل فصل المتحدثين).

تنسيق SRT

تنسيق ترجمات SubRip مع طوابع زمنية، متوافق مع مشغلات الفيديو وبرامج تحرير الترجمات النصية.

حالة الخدمة

راجع صفحة حالة KolWrite API لمعرفة التوافر المباشر وسجل وقت التشغيل وحوادث مستوى الخدمة.

GET /health لا يتطلب مفتاح API ويُرجع الحالة الحالية للـ API واستقبال المهام ومعالجة النسخ. وتعني استجابة 200 أن الخدمة تعمل أو تعمل بأداء متراجع؛ بينما تعني استجابة 503 أن الحالة الحالية غير معروفة أو غير متاحة. تتضمن كلتا الاستجابتين تفاصيل الحالة بتنسيق JSON.

GET /health/history?period=24h يُرجع سجل توافر موجزًا. الفترات المدعومة هي 24h, 7d، و 30d.

رموز الحالة