Batch API

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

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

GET/transcribe/{job_id}

هذه عملية الحالة والنتيجة الموصى بها للتكاملات المباشرة الجديدة عبر HTTP. استخدم jobId الذي أعادته العملية POST /transcribe/{lang} بوصفه job_id، واستدعِ العملية من خلفية موثوقة، وأرسل x-api-key.

تعيد القراءة الناجحة الغلاف { "message": "success", "data": ... }. استعلم عن data.status بمهلة لكل طلب ومهلة كلية محدودة للتطبيق. استمر فقط عند queued أو processing، وتوقف عند done أو failed أو cleared. استخدم data.final_result وحقول النتيجة المرتبطة فقط عند done. الحالة cleared طرفية وتعني أن النتيجة غير متاحة.

شكل V2 مخصص للتكاملات المباشرة عبر HTTP. تستخدم حزم JavaScript وPython عند الإصدار 0.18.0 مسار نتيجة V1 القديم وشكل استجابته.

مع القيمة الافتراضية save_result=false، قد تمسح القراءة الناجحة لعمل حالته done أو failed حقول النتيجة المخزنة بعد بناء الاستجابة. وقد تعيد قراءة لاحقة الحالة cleared. عيّن save_result=true عندما يجب أن يكون جلب النتيجة النهائية قابلاً للتكرار. لا يحدد API مدة احتفاظ.

المصادقة

ApiKeyAuth
x-api-key<token>

الموضع: header

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

job_id*string

معرّف عمل النسخ.

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

save_result?boolean

احتفظ بحقول النتيجة النهائية بعد هذه القراءة. القيمة الافتراضية false. مع false، قد تمسح قراءة done أو failed حقول النتيجة بعد إعادتها، وقد تعيد قراءة لاحقة الحالة cleared. عيّن true قبل الاستعلام عندما يحتاج التطبيق إلى إعادة محاولة جلب النتيجة النهائية أو جلبها مجددًا. لا يحدد هذا الخيار مدة احتفاظ.

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

application/json

application/json

application/json

application/json

application/json

application/json

curl -sS --fail-with-body --connect-timeout 10 --max-time 120 -X GET \  "https://example.com/transcribe/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Origin: https://example.com"

عمل النسخ

application/json

عمل في قائمة الانتظار

{
  "message": "success",
  "data": {
    "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "version": 1,
    "created_at": "2025-12-29T08:00:00.000Z",
    "updated_at": "2025-12-29T08:00:00.000Z",
    "language": "en",
    "audio_duration": 12.34,
    "sample_rate_hz": 16000,
    "status": "queued"
  }
}

عمل قيد المعالجة

{
  "message": "success",
  "data": {
    "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "version": 1,
    "created_at": "2025-12-29T08:00:00.000Z",
    "updated_at": "2025-12-29T08:00:02.000Z",
    "language": "en",
    "audio_duration": 12.34,
    "sample_rate_hz": 16000,
    "status": "processing"
  }
}

عمل مكتمل

{
  "message": "success",
  "data": {
    "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "version": 1,
    "created_at": "2025-12-29T08:00:00.000Z",
    "updated_at": "2025-12-29T08:00:05.000Z",
    "language": "en",
    "audio_duration": 12.34,
    "sample_rate_hz": 16000,
    "status": "done",
    "asr_result": "hello world",
    "asr_word_segments": [
      {
        "start_time": 0,
        "end_time": 0.45,
        "word": "hello"
      }
    ],
    "diarization_segments": [
      {
        "start_time": 0,
        "end_time": 1,
        "speaker": "speaker-1"
      }
    ],
    "itn_result": null,
    "itn_word_segments": null,
    "itn_output_formats": null,
    "redaction_result": null,
    "redaction_word_segments": null,
    "redaction_labels": "",
    "final_result": "hello world",
    "final_word_segments": [
      {
        "start_time": 0,
        "end_time": 0.45,
        "word": "hello"
      }
    ]
  }
}

عمل فاشل

{
  "message": "success",
  "data": {
    "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "version": 1,
    "created_at": "2025-12-29T08:00:00.000Z",
    "updated_at": "2025-12-29T08:00:05.000Z",
    "language": "en",
    "audio_duration": 12.34,
    "sample_rate_hz": 16000,
    "status": "failed"
  }
}

مُسحت النتيجة المخزنة

{
  "message": "success",
  "data": {
    "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "version": 1,
    "created_at": "2025-12-29T08:00:00.000Z",
    "updated_at": "2025-12-29T08:00:06.000Z",
    "language": "en",
    "audio_duration": 12.34,
    "sample_rate_hz": 16000,
    "status": "cleared"
  }
}

معرّف عمل أو قيمة save_result غير صالحة

application/json

معرّف عمل غير صالح

{
  "error": "error.uuid.invalid",
  "code": "VALIDATION_INVALID_UUID",
  "detail": "error.uuid.invalid",
  "job_id": "not-a-uuid",
  "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"
}

عمل النسخ غير موجود

application/json

المثال missing_job

{
  "error": "error.transcription_job.get",
  "code": "TRANSCRIPTION_JOB_NOT_FOUND",
  "detail": "transcription job not found",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

خطأ داخلي في الخادم

application/json

المثال internal

{
  "error": "error.transcription_job.get",
  "code": "SERVER_INTERNAL",
  "detail": "error.transcription_job.get",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

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

حوّل هذا الاستعلام إلى حلقة محدودة: واصل فقط عند queued وprocessing، وتوقف عند كل حالة نهائية، واضبط save_result=true عندما يجب استرجاع استجابة نهائية مفقودة مرة أخرى.

نفّذ استعلامًا محدودًا

أضف مهلة لكل طلب وموعدًا نهائيًا كليًا وتعاملًا كاملًا مع الحالات النهائية.

شغّل سير عمل SDK

استخدم وصفة تسجيل مختبرة لـSDK JavaScript أو Python بالإصدار 0.18.0.

تعامل مع إخفاقات الاستعلام

صنّف استجابات المصادقة وعدم العثور وحد المعدل والخادم.

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

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

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

قراءة V1 للتوافق فقط تستخدمها حزم SDK لـJavaScript وPython في الإصدار 0.18.0؛ استخدم V2 لتكاملات HTTP المباشرة الجديدة.

في هذه الصفحة

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