تخطَّ إلى المحتوى

إنشاء مهمة ترجمة

POST /api/v1/jobs
Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f
Content-Type: application/json
الحقلالنوعمطلوبالافتراضيالوصف
document_idسلسلة نصية✅—معرّف مستند مؤكد
target_langسلسلة نصية✅—رمز لغة الهدف
source_langسلسلة نصية—الكشف التلقائيرمز لغة المصدر
engineسلسلة نصية—xr-397bمعرّف إعداد الترجمة، انظر إعدادات الترجمة
output_modeسلسلة نصية—bilingualsingle أو bilingual
glossary_idسلسلة نصية——معرّف مسرد لهذا الحساب. تُستخدم المسردات للحسابات المدفوعة (بشرط وجود عملية دفع ناجحة واحدة على الأقل)؛ أما الحساب غير المدفوع الذي يرسل طلبًا واحدًا فيحصل على 403
include_imagesمنطقي—falseيُرجى أيضًا ترجمة النص الموجود في صور المستند.
context_translationمنطقي—falseقم بتشغيل تحسين السياق
style_presetسلسلة نصية——إعداد نمطي

يدخل المهمة التي تم إنشاؤها إلى قائمة الانتظار. يعالج كل حساب ما يصل إلى 5 ملفات في الوقت نفسه؛ ويتم إنشاء مهام إضافية وتُضاف تلقائيًا إلى القائمة، لتبدأ بمجرد انتهاء المهام السابقة. أثناء انتظار المهمة، يوضح stage_message عدد المهام المتقدمة عليها.

قبل بدء أي مهمة، يتم فحص الرصيد مقارنةً بعتبة معينة: تتطلب PDF رصيدًا يتجاوز “عدد الصفحات × 2 رصيد”; أما التنسيقات الأخرى فتعتمد على طول النص المصدر، بحيث لا يقل عن 2 رصيد. إذا كان الرصيد غير كافٍ لبدء ملف، تنتهي تلك المهمة بـ status=failed وquota_exceeded=true، ولا يتم تحصيل أي رسوم، ولا تتأثر المهام الأخرى. عند انتهاء المهمة، يتم تحصيل الاستخدام الفعلي؛ وإذا تجاوزت التكلفة الرصيد، يصبح الرصيد سالبًا، وتُسدد الديون أولاً بالرصيد الذي يصل لاحقًا، ولا يمكن بدء مهام جديدة أثناء سلبية الرصيد، لذا يجب إعادة الشحن. انظر رصيد واستخدام .

Terminal window
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"
}
الحالةالسبب
403المفتاح لا يسمح بالإعداد المختار، أو أن الحساب غير المدفوع أرسل glossary_id
404المستند أو المسرد غير موجود، أو تم حذفه، أو ينتمي إلى حساب آخر
415لا يمكن ترجمة تنسيق الملف
422الملف فارغ، أو لا يحتوي على نص قابل للترجمة، أو أن أحد المعلمات غير صالح
429عدد الطلبات كبير جدًا، أو أن قائمة الانتظار ممتلئة؛ يُرجى إعادة المحاولة بعد Retry-After

Idempotency-Key اختياري لكن يُنصح به لكل عملية إرسال. المفتاح عبارة عن 1–128 حرفًا مرئيًا من أحرف ASCII ويظل صالحًا إلى أجل غير مسمى لنفس بيانات الاعتماد:

  • نفس المفتاح، نفس الجسم: يعيد الوظيفة الأصلية (بما في ذلك تلك التي فشلت)؛ ولا يتم إنشاء أي شيء أو تحصيل أي رسوم مرتين.
  • نفس المفتاح، جسم مختلف: 409 (idempotency_request_conflict).
  • تم حذف الوظيفة الأصلية: 410 (idempotency_job_gone).

استخدم مفتاح UUID جديدًا لكل إرسال جديد، وأعد استخدام المفتاح الأصلي فقط عند إعادة محاولة نفس الإرسال.