واجهة REST للنسخ الدفعي
أرسل تسجيلًا إلى واجهة REST للنسخ الدفعي، واستعلم عن المهمة حتى حالة طرفية، وأعد المحاولة دون إنشاء مهام مكررة.
النسخ الدفعي هو مسار HTTP المباشر للتسجيلات الطويلة المكتملة (اختيار سير العمل): ارفع مرة واحدة، واستلم jobId، ثم استعلم دوريًا حتى تنتهي المهمة. أرسل x-api-key من خلفيتك؛ ولا تحتاج طلبات REST إلى ترويسة Origin (المصادقة). حدود الحجم والمدة في الحدود.
أرسل مهمة
ارفع ملف صوت واحدًا في الحقل file من جسم multipart/form-data. ينسخ هذا الطلب كلامًا مختلط اللغة بين العربية والإنجليزية مع تمييز المتحدثين:
curl -sS -X POST "$API_URL/v1/transcribe/codeswitch?diarization=1" \
-H "x-api-key: $API_KEY" \
-F "[email protected]"تعني الاستجابة 200 أن المهمة في الطابور، لا أنها انتهت (مختصرة):
{ "jobId": "e5e90424-de35-4976-8951-04edae59fae8", "status": "queued" }احفظ jobId مع عنصر العمل في تطبيقك قبل أي خطوة أخرى؛ فهو المعرّف الوحيد للمهمة.
| المحدد | الموضع | القيم | الافتراضي |
|---|---|---|---|
lang | المسار | en، ar، codeswitch، auto | مطلوب |
asr | الاستعلام | مفتاح نموذج ASR | النموذج المضبوط للغة |
diarization | الاستعلام | 0، 1، d1، d2، d3 | معطل؛ و1 يختار المستوى الافتراضي |
itn | الاستعلام | 0، 1 | معطل |
redact | الاستعلام | 0، 1 | معطل |
تعمل true وfalse حيثما تعمل 1 و0. لمفاتيح النماذج والفروق بين مستويات التمييز، راجع النماذج. يعيد مفتاح asr غير المعروف الخطأ 400 ASR_MODEL_NOT_FOUND.
استعلم عن النتيجة
اضبط JOB_ID على jobId المُعاد، ثم اقرأ المهمة عبر مسار V2:
curl -sS -X GET "$API_URL/v1/transcribe/$JOB_ID?save_result=true" \
-H "x-api-key: $API_KEY"الاستجابة (مختصرة):
{
"message": "success",
"data": {
"id": "e5e90424-de35-4976-8951-04edae59fae8",
"language": "codeswitch",
"audio_duration": 72.6085,
"status": "done",
"final_result": "Yeah, I mean, look, to start with, as you know, building infrastructure…",
"final_word_segments": [{ "start_time": 0.08, "end_time": 0.36, "word": "Yeah," }],
"diarization_segments": [{ "start_time": 0, "end_time": 14.56, "speaker": "SPEAKER_1" }]
}
}واصل الاستعلام ما دامت data.status هي queued أو processing. توقف عند done أو failed أو cleared (حالات المهمة). استعلم كل 2 s، مع مهلة لكل طلب وموعد نهائي إجمالي.
تعيد كل حالات المهمة HTTP 200. أعد محاولة قراءة أعادت 5xx (آمن مع save_result=true) وتوقف عند 404 TRANSCRIPTION_JOB_NOT_FOUND. الرموز الأخرى: رموز الأخطاء.
| المسار | الاستخدام | النص المنسوخ | توقيتات الكلمات | المتحدثون |
|---|---|---|---|---|
GET /v1/transcribe/{job_id} (V2) | التكاملات المباشرة الجديدة | data.final_result | data.final_word_segments (بلا speaker) | data.diarization_segments |
GET /v1/transcribe/{job_id}/{lang} (V1) | قديم؛ تستخدمه حزم SDK | results.transcript | results.offsets (word، startTime، endTime، speaker) | diarization_segments |
للشكلين الحالات نفسها لكن أسماء الحقول وحالة الأحرف مختلفة، فمثّل كل شكل بنوعه الخاص. مقطع {lang} في V1 مطلوب لكنه يُتجاهل. اقرأ حقول النتيجة عندما تكون الحالة done فقط؛ فـfinal_result وfinal_word_segments تتضمنان ITN والتنقيح إذا فعّلتهما. لا تتضمن استجابة failed سببًا. المهمة failed نهائية؛ وإعادة إرسال الملف تنشئ مهمة جديدة.
اقرأ النتيجة مرة أخرى
يقبل مساراً النتيجة المعامل save_result، وقيمته الافتراضية false. مع الافتراضي، قد تمسح قراءة تعيد done أو failed النتيجة المخزنة، وتعيد القراءات اللاحقة cleared. احفظ النتيجة في تخزينك الخاص بمجرد قراءة done.
مرر save_result=true في كل استعلام إذا قد تحتاج إلى قراءة النتيجة أكثر من مرة، مثلًا بعد خطأ في الشبكة أو من عامل ثانٍ.
تمييز المتحدثين بمحاذاة قسرية
إذا احتجت إلى متحدث لكل كلمة، فاستعلم من مسار V1؛ فهو يطبق القاعدة أدناه على الخادم ويضع speaker على كل كلمة في results.offsets. في V2، أسند كل كلمة إلى المقطع الذي يحتوي start_time الخاص بها؛ وإلا فاستخدم قاعدة أقرب حد أدناه.
يحدد معامل الاستعلام diarization_force_align في V1 تسمية الكلمة التي يقع startTime الخاص بها خارج كل مقاطع المتحدثين:
diarization_force_align | المتحدث لتلك الكلمة |
|---|---|
true (الافتراضي) | متحدث أقرب حد مقطع، مقيسًا من منتصف الكلمة؛ وعند التعادل يُختار المقطع الأسبق |
false | UNKNOWN_SPEAKER |
إذا لم تحتوِ النتيجة على مقاطع متحدثين، فإن speaker هي null في الحالتين. يغيّر المعامل تسميات الكلمات فقط؛ أما diarization_segments فلا تتغير. تقرأ حزم SDK مسار V1 بالقيمة الافتراضية، فتحمل إزاحات الكلمات في SDK المتحدثين أصلًا. عامل تسميات مثل SPEAKER_1 كسلاسل غير شفافة تميز المتحدثين داخل نتيجة واحدة؛ فهي لا تحدد هوية أحد.
إعادة المحاولة والتكرار
لا يوجد مفتاح idempotency للإرسال (أي عدم تكرار الأثر)، ولا نقطة نهاية لسرد المهام أو البحث عنها. إذا لم ترَ jobId، فلا يمكنك استرجاعه؛ لذا بعد رفع ملتبس تختار بين قبول مهمة مكررة محتملة وعدم إعادة الإرسال.
| نتيجة الإرسال | هل أُنشئت مهمة؟ | الإجراء |
|---|---|---|
400، 401، 402، 403، 413، 422 | لا | أصلح الطلب أو الحساب، ثم أرسل. |
429، 503 | لا | تراجع ثم أعد الإرسال (إعادة المحاولة بأمان). |
500، أو 502 أو 504 من البوابة، أو مهلة، أو اتصال منقطع | ربما | لا تعد الإرسال تلقائيًا. |
سجّل كل jobId تتلقاه، وسجّل كل إرسال لم ترَ نتيجته. قراءات النتيجة آمنة لإعادة المحاولة عندما يستخدم كل استعلام save_result=true.
استجابات السعة
عندما تُستنفد سعة الصوت الدفعي لحسابك، يعيد الإرسال 429 RATE_LIMIT_EXCEEDED مع السعة المتبقية بثواني الصوت (مختصرة):
{ "code": "RATE_LIMIT_EXCEEDED", "retryable": true, "data": { "capacity": 120.5 } }القيمة data.capacity ليست مدة انتظار. قد تعني القيمة 0 أنه لا يوجد رصيد متاح. استخدمها لتقرر هل يتسع التسجيل، وأجّل الأعمال الأكبر. قد تعيد حدود المعدل في البوابة 429 بلا هذا الجسم؛ فعامل غياب data.capacity كتراجع عادي. الخطأ 402 CREDITS_EXHAUSTED مختلف: نفد رصيد الحساب، ولن تنفع إعادة المحاولة. لقواعد التراجع، راجع إعادة المحاولة بأمان.