--- title: إرسال مهمة نسخ description: أرسل تسجيلًا مكتملًا وطويلًا للمعالجة غير المتزامنة، ثم خزّن معرّف المهمة. icon: ArrowUpFromLine full: true _openapi: method: POST webhook: false toc: [] structuredData: headings: [] contents: - content: |- أرسل تسجيلًا مكتملًا واحدًا للنسخ غير المتزامن عبر Batch. استخدم Batch للوسائط الطويلة أو الكبيرة المكتملة، وFast لوحدة حوارية واحدة مكتملة ومحدودة وحساسة لزمن الاستجابة، وRealtime فقط ما دام الصوت يصل. تعني استجابة `200` أن المهمة قُبلت بحالة `queued`، لا أن النسخ اكتمل. خزّن `jobId` ثم استعلم من `GET /transcribe/{job_id}` حتى `done` أو `failed` أو `cleared`. لا تدعم هذه العملية عقد مفتاح idempotency؛ فلا تعاود إرسال الرفع عشوائيًا بعد مهلة أو انقطاع اتصال أو استجابة `5xx`، إذ قد تكون المهمة موجودةً بالفعل وقد تنشئ الإعادة عملاً مكررًا. تمثل استجابة `429` ضغط سعة، وتكون `data.capacity` سعة معالجة الصوت المتبقية بالثواني عند توفر الرصيد، وليست مدة انتظار أو وقت إعادة ضبط. --- ## العملية **POST `/transcribe/{lang}`** - **عنوان URL الأساسي:** `https://api.voice.humain.com/v1` - **عنوان URL للطلب:** `https://api.voice.humain.com/v1/transcribe/{lang}` ## الوصف أرسل تسجيلًا مكتملًا واحدًا للنسخ غير المتزامن عبر Batch. استخدم Batch للوسائط الطويلة أو الكبيرة المكتملة، وFast لوحدة حوارية واحدة مكتملة ومحدودة وحساسة لزمن الاستجابة، وRealtime فقط ما دام الصوت يصل. تعني استجابة `200` أن المهمة قُبلت بحالة `queued`، لا أن النسخ اكتمل. خزّن `jobId` ثم استعلم من `GET /transcribe/{job_id}` حتى `done` أو `failed` أو `cleared`. لا تدعم هذه العملية عقد مفتاح idempotency. فلا تعد رفعًا عشوائيًا بعد مهلة أو انقطاع اتصال أو استجابة `5xx`؛ فقد تكون المهمة موجودة بالفعل وقد تنشئ الإعادة عملاً مكررًا. تمثل استجابة `429` ضغط سعة، وتكون `data.capacity` سعة معالجة الصوت المتبقية بالثواني عند توفر الرصيد، وليست مدة انتظار أو وقت إعادة ضبط. ## المصادقة - `ApiKeyAuth` — type: `apiKey`; الموضع: `header`; الترويسات: `x-api-key` ## المعاملات ### المعامل `lang` - **الموضع:** `path` - **مطلوب:** نعم - **النوع:** `string` رمز لغة النسخ. **المخطط:** ```yaml type: string enum: - en - ar - codeswitch - auto ``` **الأمثلة:** لا توجد قيمة موثقة. ### المعامل `asr` - **الموضع:** `query` - **مطلوب:** لا - **النوع:** `string` مفتاح دقيق اختياري لنموذج ASR. عند حذفه تستخدم الخدمة النموذج الافتراضي المضبوط لقيمة `lang` المختارة. يعيد المفتاح غير المعروف أو غياب النموذج الافتراضي الحالة `400` والرمز `ASR_MODEL_NOT_FOUND`. **المخطط:** ```yaml type: string ``` **الأمثلة:** لا توجد قيمة موثقة. ### المعامل `diarization` - **الموضع:** `query` - **مطلوب:** لا - **النوع:** `string` محدد تمييز المتحدثين: - الحذف أو `0` أو `false`: معطل - `1` أو `true`: مفعّل بالنموذج الافتراضي - `d1`: تمييز المتحدثين - `d2`: تمييز المتحدثين بالنموذج البديل **المخطط:** ```yaml type: string enum: - "0" - "1" - "false" - "true" - d1 - d2 ``` **الأمثلة:** ```yaml enable: value: "1" disable: value: "0" enable_boolean: value: "true" disable_boolean: value: "false" d1: value: d1 d2: value: d2 ``` ### المعامل `itn` - **الموضع:** `query` - **مطلوب:** لا - **النوع:** `string` محدد تطبيع النص العكسي (ITN): - الحذف أو `0` أو `false`: معطل - `1` أو `true`: مفعّل؛ يحول الصيغ المنطوقة إلى مكتوبة، مثل twenty five إلى 25 **المخطط:** ```yaml type: string enum: - "0" - "1" - "false" - "true" ``` **الأمثلة:** ```yaml enable: value: "1" disable: value: "0" enable_boolean: value: "true" disable_boolean: value: "false" ``` ### المعامل `redact` - **الموضع:** `query` - **مطلوب:** لا - **النوع:** `string` محدد تنقيح معلومات PII: - الحذف أو `0` أو `false`: معطل - `1` أو `true`: مفعّل؛ يحجب المعلومات الحساسة في النصوص **المخطط:** ```yaml type: string enum: - "0" - "1" - "false" - "true" ``` **الأمثلة:** ```yaml enable: value: "1" disable: value: "0" enable_boolean: value: "true" disable_boolean: value: "false" ``` ## جسم الطلب - **مطلوب:** نعم #### نوع المحتوى: `multipart/form-data` **المخطط:** ```yaml type: object required: - file properties: file: type: string description: |- تسجيل صوتي مكتمل واحد، وهو الجزء الصوتي الوحيد المقبول. يعيد الإدخال غير المدعوم أو التالف أو الفارغ أو صفري المدة الحالة `422`. ويعيد التسجيل الأطول من حد المدة بعد فك الترميز الحالة `422` `AUDIO_DURATION_EXCEEDED`؛ ويعيد جزء صوتي ثانٍ الحالة `422` `FILE_COUNT_EXCEEDED`. راجع «حدود الطلب». contentMediaType: application/octet-stream ``` **الأمثلة:** لا توجد قيمة موثقة. ## الاستجابات ### الاستجابة `200` قُبلت المهمة ووُضعت في قائمة المعالجة غير المتزامنة #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - jobId - status properties: jobId: type: string format: uuid status: type: string enum: - queued examples: - queued ``` **الأمثلة:** ```yaml queued: value: jobId: 7f51f2c2-e7bc-41c8-a850-f848df2ddfc8 status: queued ``` ### الاستجابة `400` لغة أو نموذج أو نوع محتوى أو جسم multipart أو حقل ملف غير صالح #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - error - code - retryable - timestamp properties: error: type: string description: معرّف الخطأ القديم، مثبت للتوافق مع الإصدارات السابقة message: type: string description: حقل الرسالة القديم، ويوجد فقط عند غياب مفتاح المصادقة code: type: string description: |- رمز خطأ قابل للقراءة آليًا. هذه القائمة هي المجموعة التي تصدرها هذه الخدمة في جسم `ErrorResponse`. أما استجابة حد المعدل `429` فتستخدم `RateLimitErrorResponse` وتحمل `RATE_LIMIT_EXCEEDED` بدلًا من ذلك. enum: - AUTH_UNAUTHORIZED - AUTH_FORBIDDEN - VALIDATION_INVALID_LANGUAGE - VALIDATION_INVALID_FORMAT - VALIDATION_REQUIRED_FIELD - VALIDATION_FILE_CORRUPT - VALIDATION_INVALID_PARAM - VALIDATION_INVALID_UUID - PAYLOAD_TOO_LARGE - AUDIO_DURATION_EXCEEDED - FILE_COUNT_EXCEEDED - ASR_TRANSCRIPTION_FAILED - ASR_MODEL_NOT_FOUND - SERVER_INTERNAL - TRANSCRIPTION_JOB_NOT_FOUND detail: type: string description: شرح خطأ مقروء للبشر job_id: type: string description: معرّف المهمة الذي أرسله العميل. قد يكون UUID صالحًا لأخطاء ما بعد الإنشاء أو القيمة غير الصالحة المرسلة عندما تكون `code` بالقيمة `VALIDATION_INVALID_UUID`. retryable: type: boolean description: ما إذا كان ينبغي للعميل إعادة محاولة الطلب timestamp: type: string format: date-time description: طابع زمني وفق ISO 8601 لوقت وقوع الخطأ request_id: type: string description: |- معرّف التتبع لهذا الطلب، للربط في طلب الدعم. موجود في حالات رفض حدود الطلب؛ وغائب عندما لا يكون التتبع مسجِّلًا. data: allOf: - type: object required: - limit - observed - unit - bound description: الحد الذي تم تجاوزه وقيمته المضبوطة وما تم رصده. properties: limit: type: integer format: int64 description: القيمة العليا المضبوطة، بوحدة `unit`. observed: type: integer format: int64 description: |- القيمة المرصودة، بوحدة `unit`. وهي أكبر من `limit` دائمًا. وتُقرَّب المدد إلى الأعلى، لذلك يبلّغ التسجيل الذي يزيد على السقف بجزء من الثانية عن قيمة أعلى منه. unit: type: string enum: - bytes - seconds - files - parts bound: type: string description: أي حد تم تجاوزه. enum: - request_bytes - audio_duration - file_parts - multipart_parts - unvalidatable_tail_bytes description: |- موجود فقط في حالة رفض لحد من حدود الطلب (`PAYLOAD_TOO_LARGE` أو `AUDIO_DURATION_EXCEEDED` أو `FILE_COUNT_EXCEEDED`). وغائب فيما عدا ذلك. ``` **الأمثلة:** ```yaml invalid_language: summary: لغة غير صالحة value: error: error.language.invalid code: VALIDATION_INVALID_LANGUAGE detail: error.language.invalid retryable: false timestamp: 2026-01-15T10:30:00Z invalid_content_type: summary: الطلب ليس بيانات نموذج multipart value: 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 missing_file: summary: حقل multipart الأول ليس file value: 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 unknown_asr_model: summary: نموذج ASR غير مضبوط value: 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 ``` ### الاستجابة `401` غير مصرح #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - error - code - retryable - timestamp properties: error: type: string description: معرّف الخطأ القديم، مثبت للتوافق مع الإصدارات السابقة message: type: string description: حقل الرسالة القديم، ويوجد فقط عند غياب مفتاح المصادقة code: type: string description: |- رمز خطأ قابل للقراءة آليًا. هذه القائمة هي المجموعة التي تصدرها هذه الخدمة في جسم `ErrorResponse`. أما استجابة حد المعدل `429` فتستخدم `RateLimitErrorResponse` وتحمل `RATE_LIMIT_EXCEEDED` بدلًا من ذلك. enum: - AUTH_UNAUTHORIZED - AUTH_FORBIDDEN - VALIDATION_INVALID_LANGUAGE - VALIDATION_INVALID_FORMAT - VALIDATION_REQUIRED_FIELD - VALIDATION_FILE_CORRUPT - VALIDATION_INVALID_PARAM - VALIDATION_INVALID_UUID - PAYLOAD_TOO_LARGE - AUDIO_DURATION_EXCEEDED - FILE_COUNT_EXCEEDED - ASR_TRANSCRIPTION_FAILED - ASR_MODEL_NOT_FOUND - SERVER_INTERNAL - TRANSCRIPTION_JOB_NOT_FOUND detail: type: string description: شرح خطأ مقروء للبشر job_id: type: string description: معرّف المهمة الذي أرسله العميل. قد يكون UUID صالحًا لأخطاء ما بعد الإنشاء أو القيمة غير الصالحة المرسلة عندما تكون `code` بالقيمة `VALIDATION_INVALID_UUID`. retryable: type: boolean description: ما إذا كان ينبغي للعميل إعادة محاولة الطلب timestamp: type: string format: date-time description: طابع زمني وفق ISO 8601 لوقت وقوع الخطأ request_id: type: string description: |- معرّف التتبع لهذا الطلب، للربط في طلب الدعم. موجود في حالات رفض حدود الطلب؛ وغائب عندما لا يكون التتبع مسجِّلًا. data: allOf: - type: object required: - limit - observed - unit - bound description: الحد الذي تم تجاوزه وقيمته المضبوطة وما تم رصده. properties: limit: type: integer format: int64 description: القيمة العليا المضبوطة، بوحدة `unit`. observed: type: integer format: int64 description: |- القيمة المرصودة، بوحدة `unit`. وهي أكبر من `limit` دائمًا. وتُقرَّب المدد إلى الأعلى، لذلك يبلّغ التسجيل الذي يزيد على السقف بجزء من الثانية عن قيمة أعلى منه. unit: type: string enum: - bytes - seconds - files - parts bound: type: string description: أي حد تم تجاوزه. enum: - request_bytes - audio_duration - file_parts - multipart_parts - unvalidatable_tail_bytes description: |- موجود فقط في حالة رفض لحد من حدود الطلب (`PAYLOAD_TOO_LARGE` أو `AUDIO_DURATION_EXCEEDED` أو `FILE_COUNT_EXCEEDED`). وغائب فيما عدا ذلك. ``` **الأمثلة:** ```yaml missing_key: value: error: auth.unauthorized message: unauthorized code: AUTH_UNAUTHORIZED retryable: false timestamp: 2026-01-15T10:30:00Z ``` ### الاستجابة `403` لا يمنح مفتاح API صلاحية الوصول إلى النسخ الدفعي #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - error - code - retryable - timestamp properties: error: type: string description: معرّف الخطأ القديم، مثبت للتوافق مع الإصدارات السابقة message: type: string description: حقل الرسالة القديم، ويوجد فقط عند غياب مفتاح المصادقة code: type: string description: |- رمز خطأ قابل للقراءة آليًا. هذه القائمة هي المجموعة التي تصدرها هذه الخدمة في جسم `ErrorResponse`. أما استجابة حد المعدل `429` فتستخدم `RateLimitErrorResponse` وتحمل `RATE_LIMIT_EXCEEDED` بدلًا من ذلك. enum: - AUTH_UNAUTHORIZED - AUTH_FORBIDDEN - VALIDATION_INVALID_LANGUAGE - VALIDATION_INVALID_FORMAT - VALIDATION_REQUIRED_FIELD - VALIDATION_FILE_CORRUPT - VALIDATION_INVALID_PARAM - VALIDATION_INVALID_UUID - PAYLOAD_TOO_LARGE - AUDIO_DURATION_EXCEEDED - FILE_COUNT_EXCEEDED - ASR_TRANSCRIPTION_FAILED - ASR_MODEL_NOT_FOUND - SERVER_INTERNAL - TRANSCRIPTION_JOB_NOT_FOUND detail: type: string description: شرح خطأ مقروء للبشر job_id: type: string description: معرّف المهمة الذي أرسله العميل. قد يكون UUID صالحًا لأخطاء ما بعد الإنشاء أو القيمة غير الصالحة المرسلة عندما تكون `code` بالقيمة `VALIDATION_INVALID_UUID`. retryable: type: boolean description: ما إذا كان ينبغي للعميل إعادة محاولة الطلب timestamp: type: string format: date-time description: طابع زمني وفق ISO 8601 لوقت وقوع الخطأ request_id: type: string description: |- معرّف التتبع لهذا الطلب، للربط في طلب الدعم. موجود في حالات رفض حدود الطلب؛ وغائب عندما لا يكون التتبع مسجِّلًا. data: allOf: - type: object required: - limit - observed - unit - bound description: الحد الذي تم تجاوزه وقيمته المضبوطة وما تم رصده. properties: limit: type: integer format: int64 description: القيمة العليا المضبوطة، بوحدة `unit`. observed: type: integer format: int64 description: |- القيمة المرصودة، بوحدة `unit`. وهي أكبر من `limit` دائمًا. وتُقرَّب المدد إلى الأعلى، لذلك يبلّغ التسجيل الذي يزيد على السقف بجزء من الثانية عن قيمة أعلى منه. unit: type: string enum: - bytes - seconds - files - parts bound: type: string description: أي حد تم تجاوزه. enum: - request_bytes - audio_duration - file_parts - multipart_parts - unvalidatable_tail_bytes description: |- موجود فقط في حالة رفض لحد من حدود الطلب (`PAYLOAD_TOO_LARGE` أو `AUDIO_DURATION_EXCEEDED` أو `FILE_COUNT_EXCEEDED`). وغائب فيما عدا ذلك. ``` **الأمثلة:** ```yaml scope_denied: value: error: error.api_key.scope_denied code: AUTH_FORBIDDEN detail: scope not permitted retryable: false timestamp: 2026-01-15T10:30:00Z ``` ### الاستجابة `413` تجاوز الطلب حد البايتات. لم تُنشأ أي مهمة ولم يبدأ أي نسخ. ويكون `data.observed` هو `Content-Length` المعلن من العميل عندما يتجاوز الحد أصلًا؛ أما عندما يُرفض الجسم أثناء قراءته فهو `limit + 1`، وهو أصغر حجم يمكن إثباته، لأن القراءة تتوقف عند تلك النقطة. #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - error - code - retryable - timestamp properties: error: type: string description: معرّف الخطأ القديم، مثبت للتوافق مع الإصدارات السابقة message: type: string description: حقل الرسالة القديم، ويوجد فقط عند غياب مفتاح المصادقة code: type: string description: |- رمز خطأ قابل للقراءة آليًا. هذه القائمة هي المجموعة التي تصدرها هذه الخدمة في جسم `ErrorResponse`. أما استجابة حد المعدل `429` فتستخدم `RateLimitErrorResponse` وتحمل `RATE_LIMIT_EXCEEDED` بدلًا من ذلك. enum: - AUTH_UNAUTHORIZED - AUTH_FORBIDDEN - VALIDATION_INVALID_LANGUAGE - VALIDATION_INVALID_FORMAT - VALIDATION_REQUIRED_FIELD - VALIDATION_FILE_CORRUPT - VALIDATION_INVALID_PARAM - VALIDATION_INVALID_UUID - PAYLOAD_TOO_LARGE - AUDIO_DURATION_EXCEEDED - FILE_COUNT_EXCEEDED - ASR_TRANSCRIPTION_FAILED - ASR_MODEL_NOT_FOUND - SERVER_INTERNAL - TRANSCRIPTION_JOB_NOT_FOUND detail: type: string description: شرح خطأ مقروء للبشر job_id: type: string description: معرّف المهمة الذي أرسله العميل. قد يكون UUID صالحًا لأخطاء ما بعد الإنشاء أو القيمة غير الصالحة المرسلة عندما تكون `code` بالقيمة `VALIDATION_INVALID_UUID`. retryable: type: boolean description: ما إذا كان ينبغي للعميل إعادة محاولة الطلب timestamp: type: string format: date-time description: طابع زمني وفق ISO 8601 لوقت وقوع الخطأ request_id: type: string description: |- معرّف التتبع لهذا الطلب، للربط في طلب الدعم. موجود في حالات رفض حدود الطلب؛ وغائب عندما لا يكون التتبع مسجِّلًا. data: allOf: - type: object required: - limit - observed - unit - bound description: الحد الذي تم تجاوزه وقيمته المضبوطة وما تم رصده. properties: limit: type: integer format: int64 description: القيمة العليا المضبوطة، بوحدة `unit`. observed: type: integer format: int64 description: |- القيمة المرصودة، بوحدة `unit`. وهي أكبر من `limit` دائمًا. وتُقرَّب المدد إلى الأعلى، لذلك يبلّغ التسجيل الذي يزيد على السقف بجزء من الثانية عن قيمة أعلى منه. unit: type: string enum: - bytes - seconds - files - parts bound: type: string description: أي حد تم تجاوزه. enum: - request_bytes - audio_duration - file_parts - multipart_parts - unvalidatable_tail_bytes description: |- موجود فقط في حالة رفض لحد من حدود الطلب (`PAYLOAD_TOO_LARGE` أو `AUDIO_DURATION_EXCEEDED` أو `FILE_COUNT_EXCEEDED`). وغائب فيما عدا ذلك. ``` **الأمثلة:** ```yaml declared_too_large: summary: "`Content-Length` يتجاوز الحد أصلًا" value: 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 unvalidatable_tail: summary: بيانات بعد التسجيل أكثر من أن يكتمل فحص الحدود value: 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 overran_while_reading: summary: تجاوز الجسم الحد في أثناء البث value: 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 ``` ### الاستجابة `422` إدخال صوتي غير مدعوم أو تالف، أو طلب صالح يتجاوز عبؤه حدًا دلاليًا. لم تُنشأ أي مهمة ولم يبدأ أي نسخ؛ راجع «حدود الطلب» لمعرفة الحالات التي يُحوَّل فيها الصوت قبل الرفض. #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - error - code - retryable - timestamp properties: error: type: string description: معرّف الخطأ القديم، مثبت للتوافق مع الإصدارات السابقة message: type: string description: حقل الرسالة القديم، ويوجد فقط عند غياب مفتاح المصادقة code: type: string description: |- رمز خطأ قابل للقراءة آليًا. هذه القائمة هي المجموعة التي تصدرها هذه الخدمة في جسم `ErrorResponse`. أما استجابة حد المعدل `429` فتستخدم `RateLimitErrorResponse` وتحمل `RATE_LIMIT_EXCEEDED` بدلًا من ذلك. enum: - AUTH_UNAUTHORIZED - AUTH_FORBIDDEN - VALIDATION_INVALID_LANGUAGE - VALIDATION_INVALID_FORMAT - VALIDATION_REQUIRED_FIELD - VALIDATION_FILE_CORRUPT - VALIDATION_INVALID_PARAM - VALIDATION_INVALID_UUID - PAYLOAD_TOO_LARGE - AUDIO_DURATION_EXCEEDED - FILE_COUNT_EXCEEDED - ASR_TRANSCRIPTION_FAILED - ASR_MODEL_NOT_FOUND - SERVER_INTERNAL - TRANSCRIPTION_JOB_NOT_FOUND detail: type: string description: شرح خطأ مقروء للبشر job_id: type: string description: معرّف المهمة الذي أرسله العميل. قد يكون UUID صالحًا لأخطاء ما بعد الإنشاء أو القيمة غير الصالحة المرسلة عندما تكون `code` بالقيمة `VALIDATION_INVALID_UUID`. retryable: type: boolean description: ما إذا كان ينبغي للعميل إعادة محاولة الطلب timestamp: type: string format: date-time description: طابع زمني وفق ISO 8601 لوقت وقوع الخطأ request_id: type: string description: |- معرّف التتبع لهذا الطلب، للربط في طلب الدعم. موجود في حالات رفض حدود الطلب؛ وغائب عندما لا يكون التتبع مسجِّلًا. data: allOf: - type: object required: - limit - observed - unit - bound description: الحد الذي تم تجاوزه وقيمته المضبوطة وما تم رصده. properties: limit: type: integer format: int64 description: القيمة العليا المضبوطة، بوحدة `unit`. observed: type: integer format: int64 description: |- القيمة المرصودة، بوحدة `unit`. وهي أكبر من `limit` دائمًا. وتُقرَّب المدد إلى الأعلى، لذلك يبلّغ التسجيل الذي يزيد على السقف بجزء من الثانية عن قيمة أعلى منه. unit: type: string enum: - bytes - seconds - files - parts bound: type: string description: أي حد تم تجاوزه. enum: - request_bytes - audio_duration - file_parts - multipart_parts - unvalidatable_tail_bytes description: |- موجود فقط في حالة رفض لحد من حدود الطلب (`PAYLOAD_TOO_LARGE` أو `AUDIO_DURATION_EXCEEDED` أو `FILE_COUNT_EXCEEDED`). وغائب فيما عدا ذلك. ``` **الأمثلة:** ```yaml unsupported_audio: value: 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 audio_too_long: summary: الصوت بعد فك الترميز يتجاوز حد المدة value: 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 too_many_files: summary: أُرسل أكثر من جزء صوتي واحد value: 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 too_many_parts: summary: أجزاء multipart أكثر مما يسمح به الطلب value: 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 ``` ### الاستجابة `429` نفدت سعة معالجة الصوت. تمثل `data.capacity` ثواني الصوت المتبقية عند توفر رصيد؛ وليست مدة إعادة محاولة أو وقت إعادة ضبط أو ضمان حصة. قد تعني القيمة صفر عدم توفر رصيد. #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - error - code - retryable - timestamp - data properties: error: type: string code: type: string enum: - RATE_LIMIT_EXCEEDED detail: type: string retryable: type: boolean timestamp: type: string format: date-time data: type: object required: - capacity properties: capacity: type: number format: float description: سعة معالجة الصوت المتبقية بالثواني عند توفر رصيد. ليست مدة إعادة محاولة أو وقت إعادة ضبط؛ وقد تعني القيمة صفر عدم توفر رصيد. ``` **الأمثلة:** ```yaml limited: value: error: error.rate_limit code: RATE_LIMIT_EXCEEDED detail: error.rate_limit retryable: true timestamp: 2026-01-15T10:30:00Z data: capacity: 120.5 ``` ### الاستجابة `500` فشل الإرسال؛ وقد تكون النتيجة ملتبسة بعد إنشاء المهمة #### نوع المحتوى: `application/json` **المخطط:** ```yaml type: object required: - error - code - retryable - timestamp properties: error: type: string description: معرّف الخطأ القديم، مثبت للتوافق مع الإصدارات السابقة message: type: string description: حقل الرسالة القديم، ويوجد فقط عند غياب مفتاح المصادقة code: type: string description: |- رمز خطأ قابل للقراءة آليًا. هذه القائمة هي المجموعة التي تصدرها هذه الخدمة في جسم `ErrorResponse`. أما استجابة حد المعدل `429` فتستخدم `RateLimitErrorResponse` وتحمل `RATE_LIMIT_EXCEEDED` بدلًا من ذلك. enum: - AUTH_UNAUTHORIZED - AUTH_FORBIDDEN - VALIDATION_INVALID_LANGUAGE - VALIDATION_INVALID_FORMAT - VALIDATION_REQUIRED_FIELD - VALIDATION_FILE_CORRUPT - VALIDATION_INVALID_PARAM - VALIDATION_INVALID_UUID - PAYLOAD_TOO_LARGE - AUDIO_DURATION_EXCEEDED - FILE_COUNT_EXCEEDED - ASR_TRANSCRIPTION_FAILED - ASR_MODEL_NOT_FOUND - SERVER_INTERNAL - TRANSCRIPTION_JOB_NOT_FOUND detail: type: string description: شرح خطأ مقروء للبشر job_id: type: string description: معرّف المهمة الذي أرسله العميل. قد يكون UUID صالحًا لأخطاء ما بعد الإنشاء أو القيمة غير الصالحة المرسلة عندما تكون `code` بالقيمة `VALIDATION_INVALID_UUID`. retryable: type: boolean description: ما إذا كان ينبغي للعميل إعادة محاولة الطلب timestamp: type: string format: date-time description: طابع زمني وفق ISO 8601 لوقت وقوع الخطأ request_id: type: string description: |- معرّف التتبع لهذا الطلب، للربط في طلب الدعم. موجود في حالات رفض حدود الطلب؛ وغائب عندما لا يكون التتبع مسجِّلًا. data: allOf: - type: object required: - limit - observed - unit - bound description: الحد الذي تم تجاوزه وقيمته المضبوطة وما تم رصده. properties: limit: type: integer format: int64 description: القيمة العليا المضبوطة، بوحدة `unit`. observed: type: integer format: int64 description: |- القيمة المرصودة، بوحدة `unit`. وهي أكبر من `limit` دائمًا. وتُقرَّب المدد إلى الأعلى، لذلك يبلّغ التسجيل الذي يزيد على السقف بجزء من الثانية عن قيمة أعلى منه. unit: type: string enum: - bytes - seconds - files - parts bound: type: string description: أي حد تم تجاوزه. enum: - request_bytes - audio_duration - file_parts - multipart_parts - unvalidatable_tail_bytes description: |- موجود فقط في حالة رفض لحد من حدود الطلب (`PAYLOAD_TOO_LARGE` أو `AUDIO_DURATION_EXCEEDED` أو `FILE_COUNT_EXCEEDED`). وغائب فيما عدا ذلك. ``` **الأمثلة:** ```yaml transcription_failed: value: 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](/ar/api-reference/batch/get-transcription-job) اقرأ شكل الحالة والنتيجة الموصى به لتكامل HTTP المباشر. ### [ابنِ دورة حياة Batch](/ar/api-guides/batch-rest) اربط الإرسال والاستعلام المحدود والتعامل مع الحالات النهائية. ### [خطط للتعامل الآمن مع الإخفاقات](/ar/api-guides/errors-and-rate-limits) تعامل مع ضغط السعة ونتائج الرفع الملتبسة من دون إعادة محاولة عشوائية.