API संदर्भ

हर एंडपॉइंट, अनुरोध और प्रतिक्रिया के स्वरूप, त्रुटि कोड, और दर सीमा के लिए पूर्ण संदर्भ।

सीमाएं और व्यवहार

मासिक टोकन भत्ता (फ्री टियर): मॉडल कॉल करने से पहले, API टोकन का अनुमान लगाता है लगभग ceil(content_length / 4) × (number_of_targets + 1) के रूप में और केवल free टियर के लिए, यदि अनुमान शेष मासिक भत्ता (डिफ़ॉल्ट 100000) से अधिक होगा तो अनुरोध को 429 / token_limit_reached के साथ अस्वीकार करता है। भुगतान किए गए स्तर इस पूर्व-जांच से अवरुद्ध नहीं होते; उपयोग अभी भी लॉग किया जाता है।

दर सीमाएं: जब 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 को पोल करें।

जब बड़े दस्तावेज़ (लंबा 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-आधारित) यह दर्शाता है कि इस कार्य से पहले कितने लंबित या संसाधित कार्य बनाए गए थे — प्रगति UI के लिए उपयोग करें। जब काउंट क्वेरी विफल हो, तो इसे छोड़ दिया जाता है।

प्रतिक्रिया (पूर्ण)

{
  "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 enterprise के लिए null हैं (रिपोर्टिंग में असीमित भत्ता)।

सामग्री प्रारूप

समर्थित format मान: plain, markdown, json, html।

RTL और आपके ऐप में दिशा

plain और markdown आउटपुट के लिए, API केवल अनुवादित टेक्स्ट लौटाता है — यह dir="rtl" या रैपर एलिमेंट्स नहीं जोड़ता। अरबी, हिब्रू, या फारसी दिखाते समय अपने UI में टेक्स्ट दिशा सेट करें (CSS direction, पैरेंट एलिमेंट का dir एट्रिब्यूट, या आपके फ्रेमवर्क की i18n लेआउट)।

html प्रारूप के लिए, अनुवादित मार्कअप में RTL लक्ष्यों के लिए उपयुक्त जगहों पर dir="rtl" शामिल हो सकता है।

त्रुटि प्रतिक्रियाएं

संभव हो तो त्रुटियां JSON होती हैं:

{
  "error": "invalid_request",
  "message": "मानव-पठनीय विवरण"
}

GET /usage 500 लौट सकता है सामान्य संदेश के साथ यदि Supabase क्वेरी विफल हो।