Batch API
Batch API
أرسل تسجيلات طويلة ومكتملة، ثم استعلم عن عمل النسخ حتى يصل إلى حالة نهائية.
اختر Batch عندما يكون التسجيل كاملًا والعمل طويلًا: اجتماع أو بودكاست أو مقابلة أو مكالمة أو أرشيف. ارفع الملف مرة واحدة، واحفظ معرّف المهمة المعاد، ثم اجلب النتيجة بصورة غير متزامنة.
HTTP المباشرة V2 وSDK بالإصدار 0.18.0
لتكامل HTTP مباشر جديد، فضّل
GET /v1/transcribe/{job_id} واستجابة V2. تستخدم أداتا JavaScript وPython بالإصدار 0.18.0 حاليًا مسار V1 القديم عند الاستعلام، لذلك احتفظ بشكل استجابته عند استخدام دوال SDK المنشورة.دورة حياة العمل
- أرسل ملفًا صوتيًا كاملًا واحدًا وسجّل
jobIdالمعاد قبل تنفيذ أي عمل آخر. - قبل الاستعلام، اضبط
save_result=trueعندما يجب استرجاع الاستجابة النهائية مجددًا بعد فقدها؛ ثم استخدم فاصلًا محدودًا وموعدًا نهائيًا كليًا وتفاوتًا عشوائيًا عند مشاركة السعة. - واصل الاستعلام ما دامت الحالة
queuedأوprocessing. - توقف عند كل حالة نهائية: استخدم ناتج
done، واعرضfailed، وتعامل معclearedكناتج لم يعد متاحًا.
نقاط النهاية
POST · إرسال مهمة نسخ
ارفع الصوت، واختر اللغة وخيارات المعالجة، واستلم معرّف المهمة.
GET · جلب عمل (V2)
الاستعلام الموصى به لتكامل HTTP المباشر مع غلاف النجاح القياسي.
GET · جلب عمل (V1 القديم)
الاستجابة القديمة التي تستخدمها دوال SDK في JavaScript وPython بالإصدار 0.18.0.
تعامل مع كل حالة نهائية
| الحالة | المعنى | إجراء العميل |
|---|---|---|
queued | في انتظار المعالجة | واصل الاستعلام ضمن الموعد النهائي |
processing | النسخ قيد التنفيذ | واصل الاستعلام ضمن الموعد النهائي |
done | الناتج جاهز | تحقق من النتيجة التي تحتاجها واحفظها |
failed | فشلت المعالجة | أوقف الاستعلام واعرض الإخفاق |
cleared | مُسح الناتج المخزن | أوقف الاستعلام ولا تنتظر نتيجة لاحقة |
ملاحظات الإنتاج
- قد يعيد الإرسال
429مع سعة الصوت المتبقية بالثواني. تراجع وحدّ إعادة المحاولة بدل إعادة الإرسال فورًا. - يكون انقضاء المهلة بعد الرفع ملتبسًا: قد تقبل الخدمة الملف حتى إن لم يتلق العميل الاستجابة. تتبع المحاولات وطابقها قبل إعادة المحاولة.
- اضبط مهلة لكل طلب وموعدًا نهائيًا كليًا للاستعلام. لا تسمح للـAPI أو حلقة SDK بالانتظار إلى الأبد.
- قد تمسح القيمة الافتراضية
save_result=falseالحقول المخزنة بعد بناء استجابةdoneأوfailed. استخدمtrueللتسليم القابل للتكرار، لكن لا تستنتج مدة احتفاظ. - استخدم Fast لعبارة حوارية واحدة، محدودة ومكتملة. أبقِ التسجيلات الطويلة على Batch.