النسخ الدفعي

استخدم Batch REST عندما يكون التسجيل الكبير أو الطويل موجودًا كاملاً ويكون الاكتمال غير المتزامن مقبولاً. فهو يناسب الاجتماعات والبودكاست والأرشيفات والملفات المكتملة المشابهة: ارفع مرة، واستلم jobId، واستعلم عن المهمة حتى حالة طرفية.

يقبل النسخ Fast أيضًا صوتًا مكتملاً، لكن اختره لوحدة محادثة واحدة حساسة لزمن الاستجابة. وإذا كان الصوت لا يزال يصل، فاستخدم سير عمل Realtime بدلاً منه.

1. جهّز خادمًا موثوقًا

تحتاج طلبات Batch المباشرة إلى القيم والقرارات التالية:

اتبع تدفق الوصول الموثق إذا لم تكن لديك القيمتان API_URL وAPI_KEY. الإعداد API_PATH خاص بـ Socket.IO ولا تستخدمه مسارات REST هذه.

2. أرسل عملاً

اختر مسار اللغة ومحددات المعالجة قبل الرفع. يطلب هذا المثال تبديل الشيفرة بين العربية والإنجليزية، وتمييز المتحدثين، والتسوية العكسية للنص:

curl --fail-with-body --connect-timeout 10 --max-time 120 \
  -X POST "$API_URL/v1/transcribe/codeswitch?asr=bayan_cs_ar_en&diarization=1&itn=1&redact=0" \
  -H "x-api-key: $API_KEY" \
  -F "file=@meeting.wav"

يعيد إنشاء المهمة الناجح HTTP 200. يتضمن التعريف المتحقق منه هذه الاستجابة:

{
  "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "status": "queued"
}

تحقق من حالة HTTP قبل تحليل شكل النجاح، ثم احتفظ بـ jobId مع عنصر العمل في تطبيقك؛ فهو المعرّف المستخدم في قراءات النتيجة التالية.

محددات المعالجة

استخدم خريطة النماذج لقيم النماذج المنشورة على البروتوكول. لا تخترع لاحقة نموذج لا تعرضها الخريطة.

3. استعلم من مسار نتيجة V2 بمهلة

اقرأ نتيجة V2 المباشرة باستخدام UUID العائد للعمل:

export JOB_ID="<jobId returned by the submission request>"
curl --fail-with-body --connect-timeout 10 --max-time 15 \
  "$API_URL/v1/transcribe/$JOB_ID?save_result=true" \
  -H "x-api-key: $API_KEY"

يعيد GET /v1/transcribe/{job_id} الشكل { "message": "success", "data": … }. اتخذ القرار من data.status فقط:

استخدم تسلسل الاستعلام المحدود التالي:

1. ضع مهلة كلية واحدة قبل أول قراءة للنتيجة.
2. أعط كل GET مهلة طلب مستقلة أقصر.
3. اقبل queued وprocessing فقط سببًا للانتظار والاستعلام مجددًا.
4. توقف فورًا عند done أو failed أو cleared.
5. توقف محليًا عند انتهاء المهلة الكلية؛ لا تستنتج حالة طرفية على الخادم من مهلة العميل.

اضبط save_result=true قبل أول استعلام عندما يجب أن يكون تسليم الاستجابة النهائية قابلاً للتكرار. مع القيمة الافتراضية false، قد تمسح قراءة done أو failed حقول النتيجة المخزنة بعد بناء الاستجابة. إذا ضاعت تلك الاستجابة، فقد تعيد القراءة التالية cleared بدل النتيجة.

فاصل الاستعلام والمهلة خياران للتطبيق، وليسا ضمانين للخدمة. توفر وصفة التسجيل حلقات JavaScript وPython محدودة.

4. افصل V1 عن V2

يستخدم الشكلان حالات المهمة الخمس نفسها، لكن أسماء الحقول وتداخلها مختلفان. لا تخلط مقاطع كلمات V2 ذات snake-case مع إزاحات V1 في نوع واحد. قد تجعل القيمة الافتراضية save_result=false استجابة done أو failed النهائية قراءة أحادية الاستهلاك في كلا المسارين. اضبطها إلى true قبل الاستعلام عندما يجب استرجاع النتيجة بعد فقد استجابة. لا يحدد العقد مدة احتفاظ حتى مع save_result=true؛ عامل cleared كحالة طرفية من دون افتراض إمكان الاستعادة.

يبقى مقطع lang في V1 للتوافق، لكن معالج النتيجة الحالي لا يستخدمه ولا يتحقق منه. ترسل حزم SDK في الإصدار 0.18.0 لغة الإرسال؛ وينبغي لعملاء HTTP المباشرين الجدد استخدام V2.

5. وفّق التمييز

لا تحتوي final_word_segments في V2 على speaker. عند تفعيل التمييز، وفّق كل كلمة مع diarization_segments بقاعدة توثقها في تطبيقك، مثل إسناد المقطع الذي يحتوي منتصف الكلمة. احتفظ بمتحدث مجهول عند عدم وجود تداخل، ما لم يتبن تطبيقك صراحة إسناد أقرب مقطع.

يمكن لمسار V1 وضع speaker على إزاحات الكلمات. يغير خيار diarization_force_align المخصص لـHTTP المباشرة تسميات تلك الإزاحات، لا diarization_segments الخام؛ ولا تعرضه حزم SDK في الإصدار 0.18.0. مع القيمة الافتراضية true، تُسند الكلمة التي يقع startTime لها خارج كل المقاطع الحقيقية إلى متحدث أقرب حد مقطع استنادًا إلى منتصف الكلمة، ويُختار المقطع الأسبق عند التعادل. مع false تستخدم UNKNOWN_SPEAKER. وإذا لم توجد مقاطع حقيقية فتبقى speaker بقيمة null.

تصف تسميات المتحدثين أدوارًا نسبية في نتيجة واحدة، ولا تثبت هوية حقيقية.

6. تعامل مع السعة والمحاولات الملتبسة

قد يعيد إرسال Batch حالة HTTP 429 مع حقول خطأ منظمة والسعة المتبقية بثواني الصوت في data.capacity:

{
  "error": "error.rate_limit",
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "error.rate_limit",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": { "capacity": 120.5 }
}

عند استجابة 429 صريحة، ضع المنتجين في طابور أو أبطئهم، وأعد المحاولة بعدد محاولات وتراجع ومهلة كلية محدودة. استخدم capacity لقرارات القبول؛ فلا يعرّفها العقد كمدة انتظار.

يختلف انقطاع الاتصال أو انتهاء المهلة بعد الرفع: قد يكون الطلب الأول أنشأ عملاً بالفعل. لا يوثق عقد Batch ترويسة لمفتاح idempotency، لذلك لا تعد الإرسال بلا تمييز. سجل المحاولة الملتبسة، ولا تعدها إلا وفق سياسة تطبيق تقبل صراحة خطر تكرار العمل. لا تستخدم محاولات محدودة لطلبات GET إلا عندما ضُبط save_result=true قبل جلب الحالة النهائية؛ فقد تتحول القراءة الهدامة الافتراضية إلى cleared بعد فقد الاستجابة. راجع الأخطاء وحدود المعدل.

7. انتقل إلى المرجع وتحققات الإنتاج

نفذ تسجيلاً ممثلاً واحدًا أولاً، ثم أبق مرجع Batch API المولد بجانب شيفرتك للمخططات الدقيقة. وقبل الإطلاق، اختبر فشل المصادقة، والصوت غير الصالح، و429، ومهل الاستعلام، والنتائج الطرفية الثلاث كلها.