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 المختارة، أو النموذج الافتراضي لـauto إذا لم يكن للغة نموذج افتراضي. يعيد المفتاح غير المعروف أو غياب النموذج الافتراضي الحالة 400 والرمز ASR_MODEL_NOT_FOUND.

diarization?string

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

  • عند حذفه أو 0 أو false: معطّل
  • 1 أو true: مفعّل بالاختيار الافتراضي (حاليًا d1)
  • d1: تمييز المتحدثين بتوازن بين الدقة والسرعة
  • d2: تمييز المتحدثين للتسجيلات التي تضم أكثر من 4 متحدثين؛ الأبطأ
  • d3: تمييز المتحدثين لـ4 متحدثين أو أقل؛ الأسرع. الصوت الأقصر من ثانية واحدة لا يُنتج مقاطع
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

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 "[email protected]"

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

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"
}

نفد رصيد الحساب، وقد أثبتت ذلك سلطة الفوترة. غير قابل لإعادة المحاولة: إعادة الإرسال نفسها تفشل بالطريقة ذاتها حتى يتغير الرصيد، ولا يُنشأ أي عمل. ويتميز عمدًا عن 429 الذي يمثل ضغط السعة ويزول من تلقاء نفسه.

application/json

المثال credits_exhausted

{
  "error": "insufficient credits",
  "code": "CREDITS_EXHAUSTED",
  "detail": "insufficient credits",
  "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"
}

تعذّر على سلطة الفوترة الوصول إلى قرار ائتماني، فأُغلق الإرسال بدل تقديم عمل غير مدفوع. قابل لإعادة المحاولة بعد تراجع محدود، ولا يُنشأ أي عمل. ويتميز عن 402 الذي يمثل نفادًا مُثبتًا لا تصلحه إعادة المحاولة.

application/json

المثال billing_unavailable

{
  "error": "billing authorization temporarily unavailable",
  "code": "BILLING_AUTHORIZATION_UNAVAILABLE",
  "detail": "billing authorization temporarily unavailable",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

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

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

في هذه الصفحة