API संदर्भ

यह दस्तावेज़ Express ऐप के व्यवहार से मेल खाता है api/app.js और रूट हैंडलर्स के तहत api/routes/।

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

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

रेट लिमिट्स: जब Upstash Redis कॉन्फ़िगर किया गया हो (UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN, और URL में प्लेसहोल्डर your-instance नहीं है), प्रति मिनट की सीमाएँ स्तर के अनुसार लागू होती हैं: फ्री 5, स्टार्टर 30, ग्रोथ 60, स्केल 120, एंटरप्राइज असीमित। सीमा पर, प्रतिक्रिया 429 होती है जिसमें error: "rate_limit_reached" होता है। यदि Redis कॉन्फ़िगर नहीं है, तो रेट लिमिटिंग छोड़ दी जाती है (देखें rateLimit.js)।

सफल रेट-लिमिटेड प्रतिक्रियाओं में X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset शामिल हो सकते हैं।

GET /health

कोई प्रमाणीकरण नहीं।

प्रतिक्रिया 200

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

GET /languages

कोई प्रमाणीकरण नहीं।

समर्थित भाषाओं की कैनोनिकल सूची लौटाता है (कोड, प्रदर्शन नाम, RTL फ्लैग)। कुल 36 प्रविष्टियाँ हैं; कोड ही targets में स्वीकार किए जाने वाले मान हैं अनुवाद एंडपॉइंट्स पर।

प्रतिक्रिया 200

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

स्रोत: api/utils/languages.js।

POST /translate

आवश्यक है Authorization: Bearer <api_key>।

एकल content स्ट्रिंग को हर भाषा में अनुवादित करता है जो targets में सूचीबद्ध है। मॉडल एक एकल JSON ऑब्जेक्ट लौटाता है जिसके कुंजी बिल्कुल अनुरोधित भाषा कोड हैं और जिनके मान अनुवादित स्ट्रिंग्स हैं (देखें formatPrompts.js)।

अनुरोध बॉडी

प्रतिक्रिया 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 क्लाइंट या प्रॉक्सी टाइमआउट से अधिक हो सकती है, तो इस एंडपॉइंट का उपयोग करें POST /translate के बजाय।

अनुरोध बॉडी

प्रतिक्रिया 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 मिलेगा।

प्रतिक्रिया (pending / processing)

{
  "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 के लिए इसका उपयोग करें। जब काउंट क्वेरी विफल हो, तो इसे छोड़ दिया जाता है।

प्रतिक्रिया (completed)

{
  "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"
  }
}

प्रतिक्रिया (failed)

{
  "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" शामिल हो सकता है; देखें formatPrompts.js और HTML परीक्षण scripts/test-translation.js।

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

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

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

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

अंतर्निहित मॉडल (सूचनात्मक)

API केवल standard और advanced को उजागर करता है। वास्तविक OpenAI मॉडल आईडी api/utils/modelRouter.js में कॉन्फ़िगर किए गए हैं और API प्रतिक्रियाओं में लौटाए नहीं जाते।