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": "ইংরেজি", "rtl": false },
    { "code": "ar", "name": "আরবি", "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 (১-ভিত্তিক) হল কতগুলো পেন্ডিং বা প্রসেসিং কাজ এই কাজের আগে তৈরি হয়েছে — এটি প্রগ্রেস 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 ১-ভিত্তিক, কিউ না থাকলে বাদ দেওয়া হয়)
  if (job.queue_position != null) console.log(`কিউ অবস্থান: ${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 যদি Supabase কোয়েরি ব্যর্থ হয় তবে সাধারণ বার্তা সহ 500 ফেরত দিতে পারে।