Batch API

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

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

GET/transcribe/{job_id}/{lang}

هذه عملية V1 للتوافق فقط، وتستخدمها حزم SDK لـJavaScript وPython في الإصدار 0.18.0. استخدم GET /transcribe/{job_id} (V2) في تكاملات HTTP المباشرة الجديدة.

استخدم jobId العائد من عملية الإرسال، واستعلم عن status مع مهلة لكل طلب وموعد نهائي كلي محدود. استمر فقط عند queued وprocessing، وتوقف عند done أو failed أو cleared. اقرأ results.transcript و results.offsets فقط عند done. لا تتضمن استجابة V1 ذات الحالة failed سبب فشل قابلاً للقراءة آليًا، وتعني cleared أن حقول النتيجة المخزنة غير متاحة. تعود حالات المهمة الخمس كلها ضمن HTTP 200؛ وتشير الاستجابات غير 2xx إلى خطأ في الطلب أو المصادقة أو التفويض أو البحث أو الخادم.

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

المصادقة

ApiKeyAuth
x-api-key<token>

الموضع: header

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

job_id*string

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

lang*string

مقطع توافق قديم مطلوب في المسار. لا يستخدم معالج V1 الحالي هذه القيمة ولا يتحقق منها. ترسل حزم SDK في الإصدار 0.18.0 لغة الإرسال. ينبغي لعملاء HTTP المباشرين الجدد استخدام GET /transcribe/{job_id}.

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

save_result?boolean

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

diarization_force_align?boolean

يتحكم فقط في results.offsets[].speaker ولا يغير diarization_segments. مع true (الافتراضي)، تُسند الكلمة التي يقع startTime لها خارج كل المقاطع الحقيقية إلى متحدث أقرب حد مقطع، استنادًا إلى منتصف الكلمة، ويُختار المقطع الأسبق عند التعادل. مع false تستخدم تلك الكلمات UNKNOWN_SPEAKER. وإذا لم توجد مقاطع حقيقية فتبقى speaker بقيمة null. لا تعرض حزم SDK في الإصدار 0.18.0 هذا الخيار. القيم المقبولة true/false أو 1/0.

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

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/en?save_result=true" \  -H "Origin: https://example.com"

استجابة النسخ القديمة

application/json

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

{
  "status": "queued",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": null
}

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

{
  "status": "processing",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": null
}

عمل مكتمل

{
  "status": "done",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": "hello world",
    "offsets": [
      {
        "word": "hello",
        "startTime": 0,
        "endTime": 0.45,
        "speaker": "speaker-1"
      },
      {
        "word": "world",
        "startTime": 0.46,
        "endTime": 0.9,
        "speaker": null
      }
    ]
  },
  "diarization_segments": [
    {
      "start_time": 0,
      "end_time": 1,
      "speaker": "speaker-1"
    }
  ]
}

عمل فاشل

{
  "status": "failed",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": null
}

حقول النتيجة المخزنة غير متاحة

{
  "status": "cleared",
  "APIVersion": "v1",
  "version": "api-version",
  "metadata": {
    "sautechVersion": "v1",
    "jobId": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
    "fileDuration": 12.34
  },
  "results": {
    "transcript": ""
  },
  "diarization_segments": []
}

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

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

قيمة `save_result` غير صالحة

{
  "error": "error.api.error.param.save_result.invalid",
  "code": "VALIDATION_INVALID_PARAM",
  "detail": "error.api.error.param.save_result.invalid",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

قيمة `diarization_force_align` غير صالحة

{
  "error": "error.api.error.param.diarization_force_align.invalid",
  "code": "VALIDATION_INVALID_PARAM",
  "detail": "error.api.error.param.diarization_force_align.invalid",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "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

المثال lookup_failed

{
  "error": "error.transcription_job.get",
  "code": "SERVER_INTERNAL",
  "detail": "error.transcription_job.get",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

المثال clear_failed

{
  "error": "error.transcription_job.clear_result_failed",
  "code": "SERVER_INTERNAL",
  "detail": "error.transcription_job.clear_result_failed",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

قيمة `save_result` غير صالحة

{
  "error": "error.api.error.param.save_result.invalid",
  "code": "VALIDATION_INVALID_PARAM",
  "detail": "error.api.error.param.save_result.invalid",
  "job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

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

أبقِ V1 فقط عندما يتطلبه التوافق مع SDK بالإصدار 0.18.0. لعميل HTTP مباشر جديد، انتقل إلى V2؛ وفي الحالتين أوقف الاستعلام عند done أو failed أو cleared.

انقل HTTP المباشرة إلى V2

استخدم عقد الحالة والنتيجة الموصى به لتكاملات HTTP الجديدة.

استخدم SDK المنشورة بأمان

اتبع وصفة 0.18.0 المختبرة التي ما زالت تستهلك شكل V1.

حدّ إعادة المحاولة والاستعلام

افصل حالات المهمة النهائية عن إخفاقات النقل وAPI.

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

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

واجهة Realtime HTTP

عمليات HTTP مباشرة لوحدة Fast المكتملة والصوت الذي ما زال يصل وتمييز المتحدثين وتسجيل بروتوكول TTS.

في هذه الصفحة

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