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

> أضف إلى منتجك الرسائل الصوتية أو محاضر الاجتماعات أو الترجمة المرئية أو صوتًا قابلًا للبحث، عبر واجهة REST غير متزامنة: ارفع الملف، وابدأ المهمة، واستقبل الـ webhook، واحفظ المقاطع.

آخر تحديث: 2026-10-08 · HTML: https://console.kolwrite.com/ar/use-cases/developers

## مسار الإنتاج

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` عند الطلب.

طلب المهمة:

```json
{
  "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

```javascript
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}` المرجع الموثوق.

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

| حاجة المنتج | الإعداد | السبب |
| --- | --- | --- |
| صوت واضح بكميات كبيرة وبتكلفة منخفضة | `model: "base"` | 0.40 وحدة (0.48 دولار) لكل ساعة |
| الخيار الافتراضي لملفات المستخدمين | `model: "oracle"` | جودة إنتاج مع إمكانية الترجمة |
| نص بلغة أخرى | نموذج Oracle مع `translate_to` | مهمة واحدة ونص مترجم |
| من قال ماذا | `include_diarization: true` | مشمول في السعر |
| ترجمة مرئية | `output_format: "srt"` | جاهزة لمشغلات الفيديو |

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

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

## أسئلة وأجوبة

### هل توجد مكتبة SDK؟

الواجهة HTTPS وJSON عاديان، فيصلح أي عميل HTTP. ملف OpenAPI 3.1 على /openapi.json يعمل مع مولّدات الكود.

### كيف أتجنب معالجة الـ webhook مرتين؟

استبعد التكرار عبر `X-KolWrite-Delivery-Id`؛ فالمحاولات المعادة تستخدم المعرّف نفسه.

### كيف يُحتسب الاستخدام؟

بالثانية من الصوت وفق سعر النموذج بوحدات الاستخدام، بلا حد أدنى. الوحدة الواحدة تساوي 1.20 دولار.

## صفحات ذات صلة

- [وكلاء الذكاء الاصطناعي والبرمجة بالإيحاء](https://console.kolwrite.com/ar/use-cases/ai-agents)
- [مراكز الاتصال ومكالمات المبيعات](https://console.kolwrite.com/ar/use-cases/call-centers)
- [المؤسسات](https://console.kolwrite.com/ar/use-cases/enterprise)
- [اللغات المدعومة](https://console.kolwrite.com/ar/languages/)

---
احصل على مفتاح API: https://console.kolwrite.com/auth?lang=ar · توثيق الـ API: https://console.kolwrite.com/ar/public_api_docs · llms.txt: https://console.kolwrite.com/llms.txt