التفريغ الصوتي للتطبيقات ومنتجات SaaS

مسار الإنتاج

1. يستدعي خادمك POST /upload لملف المستخدم ويعيد النموذج الموقّع إلى العميل، أو يرفعه بنفسه (حتى 100 MiB).
2. ابدأ المهمة مستخدمًا fileUrl المُعاد بوصفه audio_url مع webhook_url الخاص بك.
3. تحقّق من توقيع الـ webhook، واستبعد التكرار عبر X-KolWrite-Delivery-Id، ثم استدعِ GET /transcribe/{jobId} إذا كانت result_omitted صحيحة.
4. احفظ segments (النص والأوقات والمتحدثين) واعرضها، وصدّر srt أو txt عند الطلب.

طلب المهمة:

{
  "audio_url": "<fileUrl from POST /upload>",
  "model": "oracle",
  "language": "auto",
  "include_diarization": true,
  "output_format": "json",
  "webhook_url": "https://api.example.com/hooks/kolwrite",
  "webhook_secret": "<random secret>"
}

التحقق من webhooks

import crypto from "node:crypto";

// Express-style handler; rawBody is the exact request body as received.
export function verifyKolWrite(req, rawBody, secret) {
  const timestamp = req.headers["x-kolwrite-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(timestamp + "." + rawBody).digest("hex");
  const given = req.headers["x-kolwrite-signature"] || "";
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

كل إرسال يصل مرة واحدة على الأقل، ويُعاد عند الفشل. يبقى GET /transcribe/{jobId} المرجع الموثوق.

اختيار النموذج لكل مهمة

حدود يجب التصميم حولها

• الرفع المضمّن بـ Base64: حتى 4 MiB من الوسائط. الرفع الموقّع: حتى 100 MiB.
• تنتهي صلاحية نموذج الرفع الموقّع بعد 60 دقيقة، ورابط القراءة بعد 24 ساعة.
• المهام غير متزامنة: اعرض التقدم من PENDING وIN_PROGRESS.
• لا يمكن الجمع بين channel_speaker_separation وتمييز المتحدثين.

أسئلة وأجوبة