واجهة API لترجمة النصوص

تترجم واجهة API هذه النصوص عبر مهام في قائمة انتظار، بلغة هدف واحدة لكل مهمة. أرسل النص، واحتفظ بمعرّف المهمة الذي تتلقاه، واستعلم عن المهمة حتى تكتمل المعالجة. أرسل جميع الطلبات عبر HTTPS باستخدام بيانات اعتماد حسابك، إما بيانات HTTP Basic كما في الأمثلة أو رمز API، كما هو موضح في قسم المصادقة. احتفظ ببيانات الاعتماد على خادمك.

نقاط النهاية

يشترك خادما API، https://api.multi.tel وخادم التوافق https://api.multitel.net، في المهام ومفاتيح عدم التكرار والحدود والفوترة نفسها الخاصة بالحساب. ويختلفان في غلاف الاستجابة، لذا استخدم خادما واحدا باستمرار مع محلّل يتوافق معه.

على api.multi.tel، تتوفر جميع المسارات أيضا بالبادئة /v1/translate بدلا من /v3/translate. على api.multitel.net، استخدم مسارات /v3/translate.

تعرض استجابة معلومات الخدمة الحقول enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages وratesNanosPerCharacter. cpuLanguages قائمة رموز اللغات الأساسية المقبولة للترجمة القياسية. ويعرض ratesNanosPerCharacter السعر المضبوط لكل محرك مقابل كل نقطة ترميز من النص المصدر، بأجزاء من مليار من الدولار الأمريكي: تعني القيمة 5000 سعرا قدره $5 لكل مليون نقطة ترميز. لا توضح الاستجابة ما إذا كانت الترجمة المحسّنة متاحة حاليا؛ ويعيد تقدير الترجمة المحسّنة 503 عندما تكون غير متاحة. جلب هذه المعلومات مجاني.

ترجمة نص

أرسل JSON مع الترويسة Content-Type: application/json إلى POST https://api.multi.tel/v3/translate. لكل مهمة لغة هدف واحدة، لذا أرسل مهمة منفصلة لكل لغة هدف.

رموز الإعدادات المحلية هي وسوم BCP 47 تتكون من 2 إلى 63 حرفا ورقما وشرطة. تُحوّل إلى الصيغة المعيارية، لذلك يُسجّل en-us بصيغة en-US. تعيد الوسوم غير الصالحة، وكذلك und, mul أو zxx، الاستجابة 400 invalid_translation_language. يُفحص توفر الترجمة القياسية بحسب اللغة الأساسية، ويُعدّ nb وnn بمنزلة no. يُقبل هدف إقليمي مثل fr-CA ويُسجّل، لكن نتيجة الترجمة القياسية تتبع اللغة الأساسية ولا يُضمن أن تعكس المنطقة.

أبق جسم الطلب ضمن 128 KiB على هذا الخادم. أرسل النص بترميز UTF-8 بدلا من تمثيل كل محرف غير ASCII بتسلسل \u، إذ قد يؤدي ذلك إلى تجاوز طلب من 20,000 محرف الحد المسموح.

لا يقبل الجسم إلا هذه الحقول الأربعة. تُرفض أي خاصية أخرى باستجابة 400 invalid_translation_request، بما فيها idempotency_key ومعرّفات المالكين وعلامات المعالجة المجانية ومصفوفات المقاطع.

عدم التكرار وإعادة الاستخدام

يتطلب كل إرسال ترويسة Idempotency-Key بطول من 1 إلى 190 حرفا. استخدم أحرف ASCII والأرقام و-, _, . و:، دون مسافات في البداية أو النهاية؛ ويُرفض المفتاح المفقود أو المكوّن من 191 حرفا أو أكثر باستجابة 400. يقتصر نطاق المفاتيح على حسابك وعلى الترجمة، عبر كلا الخادمين وجميع بيانات اعتماد حسابك.

• يعيد المفتاح نفسه مع النص واللغات بصيغتها المعيارية والمحرك أنفسها المهمة الحالية باستجابة HTTP 200 وduplicate: true، دون رسوم إضافية.
• يعيد المفتاح نفسه مع نص أو لغات أو محرك مختلف 409 idempotency_conflict. ويعيد المفتاح نفسه 409 أيضا إذا تغيّر إصدار المعالجة منذ إنشاء مهمته. في هذه الحالة، اجلب المهمة الأصلية باستخدام معرّفها بدلا من إعادة إرسالها.
• يعيد مفتاح جديد مع النص واللغات بصيغتها المعيارية والمحرك أنفسها المهمة الحالية باستجابة HTTP 200 وduplicate: true، دون رسوم معالجة جديدة، إذا كانت هناك مهمة بهذا المحتوى وبإصدار المعالجة الحالي في قائمة الانتظار أو قيد التنفيذ أو مكتملة أو تنتظر الدفع. تظل المهمة المعاد استخدامها التي تنتظر الدفع بحاجة إلى السداد. لا يُعاد استخدام المهام الفاشلة: تُنشأ مهمة جديدة وتُفرض رسومها عند اكتمالها.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

تعيد المهمة الجديدة HTTP 202. يحتوي نص المثال على 57 نقطة ترميز، لذا بتكلفة $5 لكل مليون نقطة ترميز تكون تكلفته $0.000285. استجابة مختصرة (المعرّف مثال):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

قد يعيد الإرسال أيضا 402 insufficient_balance عندما لا يكفي الرصيد المدفوع مسبقا لتغطية المهمة مع مهامك الأخرى غير المنجزة، و429 translation_queue_full عندما يكون لدى حسابك أو الخدمة عدد كبير جدا من المهام غير المنجزة. ويعيد 503 في الحالات التالية:

• paid_translation_not_enabled أثناء تعطيل الترجمة المدفوعة.
• translation_unavailable لطلب ترجمة محسّنة أثناء عدم توفر الترجمة المحسّنة.
• translation_pricing_unavailable عندما لا يوجد سعر مضبوط للمحرك المحدد.

أعد محاولة الطلبات ذات الاستجابات 429 و503 لاحقا باستخدام المفتاح نفسه.

اختيار الجودة

يُعالج النص الطويل بأجزاء أصغر ثم يُجمع مجددا. قد تتغير فواصل الأسطر والمسافات، وقد تفقد الجملة سياقها عند حدود أجزاء المعالجة. احتفظ بالنص الأصلي وراجع النتيجة المجمّعة. تستخدم الترجمة القياسية اللغة الأساسية للوسم الإقليمي؛ وقبول الوسم وتسجيله لا يضمن صياغة إقليمية.

تعمل الترجمة القياسية على عمليات معالجة CPU. وترسل الترجمة المحسّنة النص إلى خدمة الذكاء الاصطناعي الخارجية المضبوطة. لا تزال نتائجها بحاجة إلى مراجعة؛ فالخدمة لا تضمن أن يكون أحد المحركات أدق لكل زوج لغات أو نوع نص.

الترجمة القياسية مسودة تختلف جودتها ومدة معالجتها بحسب زوج اللغات. والترجمة المحسّنة مخصصة للنص الذي يهم فيه السياق، لكنها لا تزال تتطلب مراجعة الأسماء والأرقام وصيغ النفي والالتزامات المهمة. لا يصلح أي من الخيارين الأخطاء الموجودة أصلا في نص مفرّغ، لذا احتفظ بالأصل للمقارنة.

استخدم GET /v3/translate على خادم API نفسه لفحص التوفر الحالي واللغات المدعومة للترجمة القياسية والأسعار المضبوطة. يعيد الطلب القياسي الذي لا تكون فيه اللغة الأساسية للمصدر أو للهدف ضمن cpuLanguages الاستجابة 422 translation_language_pair_unavailable. عندما يُقدّم source_language وتكون لغته الأساسية هي نفسها لغة الهدف الأساسية، يعيد الطلب 409 translation_same_language بدلا من إنشاء مهمة. تُفعّل الترجمة المحسّنة بشكل منفصل: أثناء عدم توفرها، تعيد عمليات إرسال الترجمة المحسّنة وتقديراتها 503.

الحصول على تقدير أولا

على api.multi.tel، أرسل جسم JSON نفسه إلى POST /v3/translate/estimate. لا يلزم مفتاح عدم تكرار. يطبق التقدير التحقق نفسه، بما في ذلك فحص 422 وفحص 409، لكنه لا ينشئ مهمة أو يترجم النص أو يحجز أموالا أو يفحص رصيدك أو يفرض رسوما على حسابك. ويعيد HTTP 200 مع estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd وcostUsd ضمن data. في المثال أعلاه، تكون قيمة costUsd هي 0.000285000 بالسعر القياسي. أثناء عدم توفر الترجمة المحسّنة، يعيد تقدير الترجمة المحسّنة 503 service_unavailable. تستخدم التقديرات السعر المضبوط حاليا. يُثبّت سعر المهمة عند إنشائها وتُحسب رسومها باستخدام ذلك السعر.

جلب الترجمة

يعيد الإرسال الجديد HTTP 202، وتعيد المهمة الموجودة أو المعاد استخدامها HTTP 200. احتفظ بـdata.id واستخدم سير عمل المهام المشترك. يحتوي كائن المهمة على هذه الحقول:

• id, status, engine, sourceLocale وtargetLocale.
• sourceCharacters, costUsd, costIsEstimate وpricePerMillionCharactersUsd.
• progress وcreatedAt.
• modelVersion، وهو سلسلة معتمة تمثل إصدار المعالجة.
• duplicate في استجابات المهام المعاد استخدامها.
• failureCode للمهام الفاشلة: translation_failed, translation_timeout, input_failed أو worker_lease_lost.

تعرض المهمة الفاشلة costUsd بقيمة صفر.

تحتوي المهمة المكتملة على data.result ويضم sourceLocale (فارغ إذا لم تُحدّد لغة المصدر)، targetLocale، والنص المترجم في text (نصوص المقاطع موصولة بفواصل أسطر)، وsegments. للنص المرسل عبر هذه الواجهة، يحتوي segments على عنصر واحد يتضمن النص المترجم في text ولغة الهدف في language. تُحجب نتائج المهام التي تنتظر الدفع حتى السداد.

استخدام api.multitel.net

تقبل نقطة نهاية التوافق POST https://api.multitel.net/v3/translate حقول JSON نفسها وترويسة Idempotency-Key نفسها. إذا غابت الترويسة، فإنها تقبل أيضا سلسلة idempotency_key في جسم JSON. يُرفض أي حقل إضافي آخر باستجابة 400 unsupported_translation_option. على هذا الخادم، يمكن أن يصل حجم الجسم الخام إلى 256,000 بايت، ويعيد النص الذي يتجاوز 20,000 نقطة ترميز 413 translation_too_large بدلا من 400. تُعامل قيمة source_language الفارغة كأنها محذوفة. تتضمن استجابة 429 الترويسة Retry-After: 15. يعيد هذا الخادم أيضا الأخطاء التالية:

• 400 json_body_required عندما يكون الجسم مفقودا أو JSON غير صالح أو قيمة JSON مفردة. أرسل كائن JSON.
• 400 invalid_translation_options عندما يكون text, target_language أو engine مفقودا أو فارغا أو ليس سلسلة، أو عندما لا يكون source_language سلسلة.
• 400 invalid_translation_text للنص الذي يتكون فقط من محارف بيضاء.
• 400 invalid_translation_engine لمحرك غير معروف.
• 400 idempotency_key_required لمفتاح مفقود أو فارغ أو طويل جدا، أو إذا لم يكن idempotency_key سلسلة.
• 400 invalid_job لمعرّف مهمة ذي تنسيق غير صحيح.

تستخدم استجابات خدمة الترجمة على هذا الخادم الغلاف {"status":{"code":HTTP_STATUS},"response":{...}}، حيث يكون status كائنا. اقرأ معرّف المهمة من response.id والنتيجة المكتملة من response.result. تضع الأخطاء الرمز في response.code، دون رسالة أو معرّف طلب. تُعاد أخطاء المصادقة (401) من فحص تسجيل الدخول العام للخادم، وقد يكون جسمها مختلفا، لذا افحص حالة HTTP قبل التحليل. المهام مشتركة مع الخادم الأساسي، لكن استخدم الخادم نفسه للاستعلام الدوري والسداد والاستخدام كي يتوافق محلّلك مع الغلاف. يقبل هذا الخادم أيضا حقول JSON نفسها في /v3/translate/estimate دون مفتاح عدم تكرار، ويوجد تقديره ضمن response.