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. תרגום משופר שולח טקסט לשירות ה-AI החיצוני שהוגדר. גם הפלט שלו דורש בדיקה; השירות אינו מבטיח שמנוע אחד מדויק יותר בכל צמד שפות או סוג טקסט.

תרגום רגיל הוא טיוטה שאיכותה וזמן העיבוד שלה משתנים לפי צמד השפות. תרגום משופר מיועד לטקסט שבו ההקשר חשוב, אך עדיין נדרשת בדיקה של שמות, מספרים, שלילות והתחייבויות חשובים. אף אפשרות אינה מתקנת שגיאות שכבר קיימות בתמלול המקורי, לכן שמרו את המקור להשוואה.

השתמשו ב-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. עבור טקסט שנשלח דרך API זה, 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.