הפניה ל-API

הפניה מלאה לכל נקודת קצה, צורת בקשה ותשובה, קוד שגיאה, ומגבלת קצב.

מגבלות והתנהגות

הקצאת אסימונים חודשית (תכנית חינמית): לפני קריאת המודל, ה-API מעריך אסימונים כבערך ceil(content_length / 4) × (number_of_targets + 1) ועבור תכנית free בלבד, דוחה את הבקשה עם 429 / token_limit_reached אם ההערכה תעלה על ההקצאה החודשית שנותרה (ברירת מחדל 100000). תכניות בתשלום אינן נחסמות על ידי בדיקה מוקדמת זו; השימוש עדיין מתועד.

מגבלות קצב: כאשר Redis מוגדר, חלות מגבלות לדקה לפי תכנית: חינמית 5, מתחילים 30, גדילה 60, סקייל 120, ארגוני ללא הגבלה. בעת הגעה למגבלה, התגובה היא 429 עם error: "rate_limit_reached". אם Redis אינו מוגדר, מגבלת הקצב מדולגת.

תגובות מוצלחות עם מגבלת קצב עשויות לכלול X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GET /health

ללא אימות.

תגובה 200

{
  "status": "ok",
  "timestamp": "2025-03-23T12:00:00.000Z"
}

GET /languages

ללא אימות.

מחזיר את הרשימה הקאנונית של השפות הנתמכות (קוד, שם תצוגה, דגל RTL). יש 43 ערכים — 36 שפות בסיס ו-7 וריאנטים אזוריים. וריאנטים אזוריים משתמשים בתתי-תגיות אזור BCP-47 (למשל fr-CA, pt-BR, es-MX). קודים מנקודת קצה זו הם הערכים היחידים שמתקבלים ב-targets בנקודות הקצה של תרגום.

תגובה 200

{
  "languages": [
    { "code": "en", "name": "English", "rtl": false },
    { "code": "ar", "name": "Arabic", "rtl": true }
  ]
}

הרשימה החיה זמינה גם דרך GET /languages — ראו למטה.

POST /translate

דורש Authorization: Bearer <api_key>.

מתרגם מחרוזת content יחידה לכל שפה ברשימת targets. התגובה היא אובייקט JSON יחיד שמפתחותיו הם בדיוק קודי השפה המבוקשים וערכיו הם המחרוזות המתורגמות.

גוף הבקשה

תגובה 200

{
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard",
    "detected_format": "markdown",
    "detection_confidence": 0.95
  }
}

detected_format ו-detection_confidence מופיעים רק כאשר format הושמט והזיהוי האוטומטי הופעל.

דוגמה (cURL)

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "{\"title\":\"Hello\"}",
    "format": "json",
    "targets": ["fr", "de"]
  }'

דוגמה (Python 3)

pip install requests

import os, requests

url = "https://api.usepolylingo.com/v1/translate"
headers = {
    "Authorization": f"Bearer {os.environ['POLYLINGO_API_KEY']}",
    "Content-Type": "application/json",
}
r = requests.post(url, json={
    "content": "<p>Hello <strong>world</strong></p>",
    "format": "html",
    "targets": ["es"],
}, timeout=120)
r.raise_for_status()
print(r.json()["translations"]["es"])

POST /translate/batch

דורש Authorization: Bearer <api_key>.

מעבד כל פריט ברצף (קריאת מודל אחת לכל פריט). אם פריט כלשהו נכשל, ה-API מחזיר 500 ואינו מחזיר תוצאות חלקיות עבור אותה בקשה.

גוף הבקשה

תגובה 200

{
  "results": [
    { "id": "welcome", "translations": { "fr": "...", "de": "..." } },
    { "id": "goodbye", "translations": { "fr": "...", "de": "..." } }
  ],
  "usage": {
    "total_tokens": 900,
    "input_tokens": 400,
    "output_tokens": 500,
    "model": "standard"
  }
}

דוגמה

curl -sS -X POST "https://api.usepolylingo.com/v1/translate/batch" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "a", "content": "Hello", "format": "plain" },
      { "id": "b", "content": "## Title", "format": "markdown" }
    ],
    "targets": ["es", "it"]
  }'

POST /jobs

דורש Authorization: Bearer <api_key>.

מכניס לעבודה תרגום ומחזיר מיד עם job_id. התרגום מתבצע ברקע — ללא סיכון של תזמון HTTP ללא קשר לגודל התוכן. בצע פולינג ל-GET /jobs/:id לקבלת התוצאה.

השתמש בנקודת קצה זו במקום POST /translate כאשר מתרגמים מסמכים גדולים (Markdown ארוך, שפות יעד רבות) שבהם משך הבקשה עלול לעלות על זמן ההמתנה של לקוח HTTP או פרוקסי.

גוף הבקשה

תגובה 202

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z"
}

GET /jobs/:id

דורש Authorization: Bearer <api_key>.

מבצע פולינג למצב עבודה שהוגשה דרך POST /jobs. בצע פולינג כל 5–10 שניות. עבודות שייכות למשתמש שהגיש אותן — משתמשים אחרים יקבלו 404.

תגובה (ממתין / בעיבוד)

{
  "job_id": "a1b2c3d4-...",
  "status": "pending",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:00.000Z",
  "completed_at": null,
  "queue_position": 3
}

status הוא pending (ממתין לעובד) או processing (העובד תפס את העבודה). queue_position (מתחיל ב-1) הוא כמה עבודות ממתינות או בעיבוד נוצרו לפני עבודה זו — השתמש בו לממשק משתמש של התקדמות. מושמט כאשר שאילתת הספירה נכשלת.

תגובה (הושלם)

{
  "job_id": "a1b2c3d4-...",
  "status": "completed",
  "created_at": "2025-03-23T12:00:00.000Z",
  "updated_at": "2025-03-23T12:00:02.000Z",
  "completed_at": "2025-03-23T12:00:02.000Z",
  "translations": {
    "es": "...",
    "fr": "..."
  },
  "usage": {
    "input_tokens": 120,
    "output_tokens": 340,
    "total_tokens": 460,
    "model": "standard"
  }
}

תגובה (נכשל)

{
  "job_id": "a1b2c3d4-...",
  "status": "failed",
  "error": "Model returned invalid JSON"
}

דוגמה (JavaScript)

const API = 'https://api.usepolylingo.com/v1'
const headers = {
  'Authorization': `Bearer ${process.env.POLYLINGO_API_KEY}`,
  'Content-Type': 'application/json',
}

// 1. שליחה
const submit = await fetch(`${API}/jobs`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ content: longMarkdown, format: 'markdown', targets: ['de', 'fr'] }),
})
const { job_id } = await submit.json()

// 2. פולינג
while (true) {
  await new Promise(r => setTimeout(r, 10_000))
  const poll = await fetch(`${API}/jobs/${job_id}`, { headers })
  const job = await poll.json()
  if (job.status === 'completed') { console.log(job.translations); break }
  if (job.status === 'failed')    { throw new Error(job.error) }
  // אופציונלי: הצגת התקדמות (queue_position מתחיל ב-1, מושמט כשלא בתור)
  if (job.queue_position != null) console.log(`Queue position: ${job.queue_position}`)
}

GET /usage

דורש Authorization: Bearer <api_key> (חיפוש מפתח סטנדרטי — לא הנתיב הפנימי בלבד).

מחזיר שימוש באסימונים עבור החודש בלוח השנה הנוכחי עבור המשתמש המאומת.

תגובה 200

{
  "period_start": "2025-03-01T00:00:00.000Z",
  "period_end": "2025-03-31T23:59:59.000Z",
  "tokens_used": 12000,
  "tokens_included": 100000,
  "tokens_remaining": 88000,
  "overage_tokens": 0,
  "tier": "free"
}

tokens_included ו-tokens_remaining הם null עבור enterprise (הקצאה בלתי מוגבלת בדיווח).

פורמטים של תוכן

ערכי format נתמכים: plain, markdown, json, html.

RTL וכיוון באפליקציה שלך

עבור פלט plain ו-markdown, ה-API מחזיר רק טקסט מתורגם — אינו מוסיף dir="rtl" או אלמנטים עוטפים. הגדר כיוון טקסט בממשק המשתמש שלך (CSS direction, תכונת dir של אלמנט אב, או פריסת i18n של המסגרת שלך) בעת הצגת ערבית, עברית או פרסית.

עבור פורמט html, סימון מתורגם עשוי לכלול dir="rtl" במקומות המתאימים ליעדי RTL.

תגובות שגיאה

שגיאות הן JSON כשאפשרי:

{
  "error": "invalid_request",
  "message": "פרט קריא לבן אדם"
}

GET /usage עשוי להחזיר 500 עם הודעה כללית אם שאילתת Supabase נכשלת.