Batch API

إرسال مهمة نسخ

أرسل تسجيلًا مكتملًا وطويلًا للمعالجة غير المتزامنة، ثم خزّن معرّف المهمة.

POST/transcribe/{lang}

أرسل تسجيلًا مكتملًا واحدًا للنسخ غير المتزامن عبر Batch. استخدم Batch للوسائط الطويلة أو الكبيرة المكتملة، وFast لوحدة حوارية واحدة مكتملة ومحدودة وحساسة لزمن الاستجابة، وRealtime فقط ما دام الصوت يصل.

تعني استجابة 200 أن المهمة قُبلت بحالة queued، لا أن النسخ اكتمل. خزّن jobId ثم استعلم من GET /transcribe/{job_id} حتى done أو failed أو cleared.

لا تدعم هذه العملية عقد مفتاح idempotency. فلا تعد رفعًا عشوائيًا بعد مهلة أو انقطاع اتصال أو استجابة 5xx؛ فقد تكون المهمة موجودة بالفعل وقد تنشئ الإعادة عملاً مكررًا. تمثل استجابة 429 ضغط سعة، وتكون data.capacity سعة معالجة الصوت المتبقية بالثواني عند توفر الرصيد، وليست مدة انتظار أو وقت إعادة ضبط.

المصادقة

ApiKeyAuth
x-api-key<token>

الموضع: header

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

lang*string

رمز لغة النسخ.

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

asr?string

مفتاح دقيق اختياري لنموذج ASR. عند حذفه تستخدم الخدمة النموذج الافتراضي المضبوط لقيمة lang المختارة. يعيد المفتاح غير المعروف أو غياب النموذج الافتراضي الحالة 400 والرمز ASR_MODEL_NOT_FOUND.

diarization?string

محدد تمييز المتحدثين:

  • الحذف أو 0 أو false: معطل
  • 1 أو true: مفعّل بالنموذج الافتراضي
  • d1: تمييز المتحدثين
  • d2: تمييز المتحدثين بالنموذج البديل
itn?string

محدد تطبيع النص العكسي (ITN):

  • الحذف أو 0 أو false: معطل
  • 1 أو true: مفعّل؛ يحول الصيغ المنطوقة إلى مكتوبة، مثل twenty five إلى 25
redact?string

محدد تنقيح معلومات PII:

  • الحذف أو 0 أو false: معطل
  • 1 أو true: مفعّل؛ يحجب المعلومات الحساسة في النصوص

جسم الطلب

multipart/form-data

تعريفات TypeScript

استخدم هذا النوع في TypeScript.

جسم الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -sS --fail-with-body --connect-timeout 10 --max-time 120 -X POST \  "https://example.com/transcribe/en?diarization=1&itn=1&redact=1" \  -H "Origin: https://example.com" \  -F "file=@meeting.wav"

قُبلت المهمة ووُضعت في قائمة المعالجة غير المتزامنة

application/json

المثال queued

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

لغة أو نموذج أو نوع محتوى أو جسم multipart أو حقل ملف غير صالح

application/json

لغة غير صالحة

{
  "error": "error.language.invalid",
  "code": "VALIDATION_INVALID_LANGUAGE",
  "detail": "error.language.invalid",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

الطلب ليس بيانات نموذج multipart

{
  "error": "error.api.error.request.invalid_format",
  "code": "VALIDATION_INVALID_FORMAT",
  "detail": "error.api.error.request.invalid_format",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

حقل multipart الأول ليس file

{
  "error": "error.api.error.multipart.file.missing",
  "code": "VALIDATION_REQUIRED_FIELD",
  "detail": "error.api.error.multipart.file.missing",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

نموذج ASR غير مضبوط

{
  "error": "error.asr_model.not_found",
  "code": "ASR_MODEL_NOT_FOUND",
  "detail": "error.asr_model.not_found",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

غير مصرح

application/json

المثال missing_key

{
  "error": "auth.unauthorized",
  "message": "unauthorized",
  "code": "AUTH_UNAUTHORIZED",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

لا يمنح مفتاح API صلاحية الوصول إلى النسخ الدفعي

application/json

المثال scope_denied

{
  "error": "error.api_key.scope_denied",
  "code": "AUTH_FORBIDDEN",
  "detail": "scope not permitted",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

تجاوز الطلب حد البايتات. لم تُنشأ أي مهمة ولم يبدأ أي نسخ. ويكون data.observed هو Content-Length المعلن من العميل عندما يتجاوز الحد أصلًا؛ أما عندما يُرفض الجسم أثناء قراءته فهو limit + 1، وهو أصغر حجم يمكن إثباته، لأن القراءة تتوقف عند تلك النقطة.

application/json

`Content-Length` يتجاوز الحد أصلًا

{
  "error": "error.api.error.request.too_large",
  "code": "PAYLOAD_TOO_LARGE",
  "detail": "error.api.error.request.too_large",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "request_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "data": {
    "limit": 536870912,
    "observed": 1073741824,
    "unit": "bytes",
    "bound": "request_bytes"
  }
}

بيانات بعد التسجيل أكثر من أن يكتمل فحص الحدود

{
  "error": "error.api.error.request.unvalidatable_tail",
  "code": "PAYLOAD_TOO_LARGE",
  "detail": "error.api.error.request.unvalidatable_tail",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 524288,
    "observed": 524289,
    "unit": "bytes",
    "bound": "unvalidatable_tail_bytes"
  }
}

تجاوز الجسم الحد في أثناء البث

{
  "error": "error.api.error.request.too_large",
  "code": "PAYLOAD_TOO_LARGE",
  "detail": "error.api.error.request.too_large",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 536870912,
    "observed": 536870913,
    "unit": "bytes",
    "bound": "request_bytes"
  }
}

إدخال صوتي غير مدعوم أو تالف، أو طلب صالح يتجاوز عبؤه حدًا دلاليًا. لم تُنشأ أي مهمة ولم يبدأ أي نسخ؛ راجع «حدود الطلب» لمعرفة الحالات التي يُحوَّل فيها الصوت قبل الرفض.

application/json

المثال unsupported_audio

{
  "error": "unsupported or corrupt audio input for conversion",
  "code": "VALIDATION_FILE_CORRUPT",
  "detail": "unsupported or corrupt audio input for conversion",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

الصوت بعد فك الترميز يتجاوز حد المدة

{
  "error": "error.api.error.audio.duration_exceeded",
  "code": "AUDIO_DURATION_EXCEEDED",
  "detail": "error.api.error.audio.duration_exceeded",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "request_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "data": {
    "limit": 14400,
    "observed": 21600,
    "unit": "seconds",
    "bound": "audio_duration"
  }
}

أُرسل أكثر من جزء صوتي واحد

{
  "error": "error.api.error.multipart.file.count_exceeded",
  "code": "FILE_COUNT_EXCEEDED",
  "detail": "error.api.error.multipart.file.count_exceeded",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 1,
    "observed": 2,
    "unit": "files",
    "bound": "file_parts"
  }
}

أجزاء multipart أكثر مما يسمح به الطلب

{
  "error": "error.api.error.multipart.part.count_exceeded",
  "code": "FILE_COUNT_EXCEEDED",
  "detail": "error.api.error.multipart.part.count_exceeded",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 8,
    "observed": 9,
    "unit": "parts",
    "bound": "multipart_parts"
  }
}

نفدت سعة معالجة الصوت. تمثل data.capacity ثواني الصوت المتبقية عند توفر رصيد؛ وليست مدة إعادة محاولة أو وقت إعادة ضبط أو ضمان حصة. قد تعني القيمة صفر عدم توفر رصيد.

application/json

المثال limited

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

فشل الإرسال؛ وقد تكون النتيجة ملتبسة بعد إنشاء المهمة

application/json

المثال transcription_failed

{
  "error": "error.api.transcription",
  "code": "ASR_TRANSCRIPTION_FAILED",
  "detail": "error.api.transcription",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

الخطوات التالية

بعد أن يعيد الطلب jobId، خزّنه قبل مغادرة معالج الطلب. ثم استعلم عبر V2 بموعد نهائي محدود حتى تصل المهمة إلى done أو failed أو cleared.

استعلم عن المهمة عبر V2

اقرأ شكل الحالة والنتيجة الموصى به لتكامل HTTP المباشر.

ابنِ دورة حياة Batch

اربط الإرسال والاستعلام المحدود والتعامل مع الحالات النهائية.

خطط للتعامل الآمن مع الإخفاقات

تعامل مع ضغط السعة ونتائج الرفع الملتبسة من دون إعادة محاولة عشوائية.

Batch API

أرسل تسجيلات طويلة ومكتملة، ثم استعلم عن عمل النسخ حتى يصل إلى حالة نهائية.

جلب حالة عمل النسخ أو نتيجته (V2)

استعلم عن حالة عمل Batch ونتيجته عبر مسار V2 الموصى به للتكاملات المباشرة الجديدة.

في هذه الصفحة

الخطوات التالية