إنشاء مهمة ترجمة
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/json| الحقل | النوع | مطلوب | الافتراضي | الوصف |
|---|---|---|---|---|
document_id | سلسلة نصية | ✅ | — | معرّف مستند مؤكد |
target_lang | سلسلة نصية | ✅ | — | رمز لغة الهدف |
source_lang | سلسلة نصية | — | الكشف التلقائي | رمز لغة المصدر |
engine | سلسلة نصية | — | xr-397b | معرّف إعداد الترجمة، انظر إعدادات الترجمة |
output_mode | سلسلة نصية | — | bilingual | single أو bilingual |
glossary_id | سلسلة نصية | — | — | معرّف مسرد لهذا الحساب. تُستخدم المسردات للحسابات المدفوعة (بشرط وجود عملية دفع ناجحة واحدة على الأقل)؛ أما الحساب غير المدفوع الذي يرسل طلبًا واحدًا فيحصل على 403 |
include_images | منطقي | — | false | يُرجى أيضًا ترجمة النص الموجود في صور المستند. |
context_translation | منطقي | — | false | قم بتشغيل تحسين السياق |
style_preset | سلسلة نصية | — | — | إعداد نمطي |
يدخل المهمة التي تم إنشاؤها إلى قائمة الانتظار. يعالج كل حساب ما يصل إلى 5 ملفات في الوقت نفسه؛ ويتم إنشاء مهام إضافية وتُضاف تلقائيًا إلى القائمة، لتبدأ بمجرد انتهاء المهام السابقة. أثناء انتظار المهمة، يوضح stage_message عدد المهام المتقدمة عليها.
قبل بدء أي مهمة، يتم فحص الرصيد مقارنةً بعتبة معينة: تتطلب PDF رصيدًا يتجاوز “عدد الصفحات × 2 رصيد”; أما التنسيقات الأخرى فتعتمد على طول النص المصدر، بحيث لا يقل عن 2 رصيد. إذا كان الرصيد غير كافٍ لبدء ملف، تنتهي تلك المهمة بـ status=failed وquota_exceeded=true، ولا يتم تحصيل أي رسوم، ولا تتأثر المهام الأخرى. عند انتهاء المهمة، يتم تحصيل الاستخدام الفعلي؛ وإذا تجاوزت التكلفة الرصيد، يصبح الرصيد سالبًا، وتُسدد الديون أولاً بالرصيد الذي يصل لاحقًا، ولا يمكن بدء مهام جديدة أثناء سلبية الرصيد، لذا يجب إعادة الشحن. انظر رصيد واستخدام .
curl --fail-with-body -X POST https://omnidoc.top/api/v1/jobs \ -H "X-API-Key: $OMNIDOC_API_KEY" \ -H "Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f" \ -H "Content-Type: application/json" \ -d '{"document_id":"4q8mx2q9z1k7p6ra","target_lang":"en"}'الاستجابة 201 (الخادم stage_message باللغة الصينية):
{ "id": "q3f8s6c2a9m1k4tx", "document_id": "4q8mx2q9z1k7p6ra", "source_lang": null, "target_lang": "en", "engine": "xr-397b", "status": "pending", "stage": "queued", "stage_progress": 0, "stage_message": "排队中", "time_cost": 0, "error_msg": null, "quota_exceeded": false, "queue_position": null, "created_at": "2026-10-01T12:01:00Z", "updated_at": "2026-10-01T12:01:00Z"}الأخطاء
Section titled “الأخطاء”| الحالة | السبب |
|---|---|
403 | المفتاح لا يسمح بالإعداد المختار، أو أن الحساب غير المدفوع أرسل glossary_id |
404 | المستند أو المسرد غير موجود، أو تم حذفه، أو ينتمي إلى حساب آخر |
415 | لا يمكن ترجمة تنسيق الملف |
422 | الملف فارغ، أو لا يحتوي على نص قابل للترجمة، أو أن أحد المعلمات غير صالح |
429 | عدد الطلبات كبير جدًا، أو أن قائمة الانتظار ممتلئة؛ يُرجى إعادة المحاولة بعد Retry-After |
التكافؤ
Section titled “التكافؤ”Idempotency-Key اختياري لكن يُنصح به لكل عملية إرسال. المفتاح عبارة عن 1–128 حرفًا مرئيًا من أحرف ASCII ويظل صالحًا إلى أجل غير مسمى لنفس بيانات الاعتماد:
- نفس المفتاح، نفس الجسم: يعيد الوظيفة الأصلية (بما في ذلك تلك التي فشلت)؛ ولا يتم إنشاء أي شيء أو تحصيل أي رسوم مرتين.
- نفس المفتاح، جسم مختلف:
409(idempotency_request_conflict). - تم حذف الوظيفة الأصلية:
410(idempotency_job_gone).
استخدم مفتاح UUID جديدًا لكل إرسال جديد، وأعد استخدام المفتاح الأصلي فقط عند إعادة محاولة نفس الإرسال.