إرسال مهمة نسخ
أرسل تسجيلًا مكتملًا وطويلًا للمعالجة غير المتزامنة، ثم خزّن معرّف المهمة.
/transcribe/{lang}أرسل تسجيلًا مكتملًا واحدًا للنسخ غير المتزامن عبر Batch. استخدم Batch للوسائط الطويلة أو الكبيرة المكتملة، وFast لوحدة حوارية واحدة مكتملة ومحدودة وحساسة لزمن الاستجابة، وRealtime فقط ما دام الصوت يصل.
تعني استجابة 200 أن المهمة قُبلت بحالة queued، لا أن النسخ اكتمل. خزّن
jobId ثم استعلم من GET /transcribe/{job_id} حتى done أو failed
أو cleared.
لا تدعم هذه العملية عقد مفتاح idempotency. فلا تعد رفعًا عشوائيًا بعد مهلة أو
انقطاع اتصال أو استجابة 5xx؛ فقد تكون المهمة موجودة بالفعل وقد تنشئ
الإعادة عملاً مكررًا. تمثل استجابة 429 ضغط سعة، وتكون data.capacity
سعة معالجة الصوت المتبقية بالثواني عند توفر الرصيد، وليست مدة انتظار أو وقت
إعادة ضبط.
المصادقة
ApiKeyAuth الموضع: header
معاملات المسار
رمز لغة النسخ.
معاملات الاستعلام
مفتاح دقيق اختياري لنموذج ASR. عند حذفه تستخدم الخدمة النموذج الافتراضي
المضبوط لقيمة lang المختارة، أو النموذج الافتراضي لـauto إذا لم يكن للغة
نموذج افتراضي. يعيد المفتاح غير المعروف أو غياب النموذج الافتراضي الحالة 400
والرمز ASR_MODEL_NOT_FOUND.
محدد تمييز المتحدثين:
- عند حذفه أو
0أوfalse: معطّل 1أوtrue: مفعّل بالاختيار الافتراضي (حاليًاd1)d1: تمييز المتحدثين بتوازن بين الدقة والسرعةd2: تمييز المتحدثين للتسجيلات التي تضم أكثر من 4 متحدثين؛ الأبطأd3: تمييز المتحدثين لـ4 متحدثين أو أقل؛ الأسرع. الصوت الأقصر من ثانية واحدة لا يُنتج مقاطع
محدد تطبيع النص العكسي (ITN):
- الحذف أو
0أوfalse: معطل 1أوtrue: مفعّل؛ يحول الصيغ المنطوقة إلى مكتوبة، مثل twenty five إلى 25
محدد تنقيح معلومات 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.