Marejeo ya API

Marejeo kamili kwa kila sehemu ya mwisho, muundo wa ombi na jibu, msimbo wa kosa, na kikomo cha kiwango.

Mipaka na tabia

Kiasi cha tokeni kwa mwezi (ngazi ya bure): Kabla ya kuita modeli, API inakadiria tokeni takriban kama ceil(content_length / 4) × (number_of_targets + 1) na, kwa ngazi ya free tu, inakataa ombi na 429 / token_limit_reached ikiwa makadirio yatazidi ruzuku ya mwezi iliyobaki (chaguo-msingi 100000). Ngazi za kulipwa hazizuiziwi na ukaguzi huu wa awali; matumizi bado yanarekodiwa.

Mipaka ya kiwango: Wakati Redis imewekwa, mipaka kwa dakika hutumika kwa ngazi: free 5, starter 30, growth 60, scale 120, enterprise isiyo na kikomo. Wakati kikomo kinapofikiwa, jibu ni 429 na error: "rate_limit_reached". Ikiwa Redis haijasanidiwa, ukomo wa kiwango hauzingatiwi.

Majibu yaliyofanikiwa yenye ukomo wa kiwango yanaweza kujumuisha X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GET /health

Hakuna uthibitishaji.

Jibu 200

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

GET /languages

Hakuna uthibitishaji.

Inarudisha orodha halali ya lugha zinazotegemewa (msimbo, jina la kuonyesha, bendera ya RTL). Kuna 43 rekodi — lugha 36 za msingi na aina 7 za kikanda. Aina za kikanda hutumia vitambulisho vya eneo vya BCP-47 (mfano fr-CA, pt-BR, es-MX). Misimbo kutoka sehemu hii pekee ndiyo inayokubaliwa katika targets kwenye sehemu za kutafsiri.

Jibu 200

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

Orodha ya moja kwa moja pia inapatikana kupitia GET /languages — angalia hapa chini.

POST /translate

Inahitaji Authorization: Bearer <api_key>.

Hutafsiri kamba moja ya content kwa kila lugha iliyoorodheshwa katika targets. Jibu ni kitu kimoja cha JSON ambacho funguo zake ni hasa misimbo ya lugha iliyohitajika na thamani zake ni kamba zilizotafsiriwa.

Mwili wa ombi

Jibu 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 na detection_confidence huonekana tu wakati format haikutajwa na utambuzi wa kiotomatiki ulifanyika.

Mfano (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"]
  }'

Mfano (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

Inahitaji Authorization: Bearer <api_key>.

Huchakata kila kipengee mfululizo (mmoja kwa mmoja kwa kila kipengee). Ikiwa kipengee chochote kinashindwa, API inarudisha 500 na hairejeshi matokeo ya sehemu kwa ombi hilo.

Mwili wa ombi

Jibu 200

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

Mfano

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

Inahitaji Authorization: Bearer <api_key>.

Inaweka kazi ya tafsiri kwenye foleni na inarudisha mara moja na job_id. Tafsiri inaendeshwa nyuma ya pazia — hakuna hatari ya muda wa HTTP bila kujali ukubwa wa maudhui. Fuatilia GET /jobs/:id kwa matokeo.

Tumia sehemu hii badala ya POST /translate wakati unatafsiri nyaraka kubwa (Markdown ndefu, lugha nyingi za lengo) ambapo muda wa ombi unaweza kuzidi muda wa mteja wako wa HTTP au proxy.

Mwili wa ombi

Jibu 202

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

GET /jobs/:id

Inahitaji Authorization: Bearer <api_key>.

Hufuatilia hali ya kazi iliyotumwa kupitia POST /jobs. Fuatilia kila 5–10 sekunde. Kazi zinamilikiwa na mtumiaji aliyetuma — watumiaji wengine hupokea 404.

Jibu (inangojea / inachakata)

{
  "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 ni pending (inangojea mfanyakazi) au processing (mfanyakazi ameichukua). queue_position (kuanzia 1) ni idadi ya kazi zinazongojea au zinazochakatwa zilizoundwa kabla ya hii — tumia kwa UI ya maendeleo. Haijatajwa wakati swali la kuhesabu linashindwa.

Jibu (imekamilika)

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

Jibu (imekosea)

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

Mfano (JavaScript)

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

// 1. Tuma
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. Fuatilia
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) }
  // Hiari: onyesha maendeleo (queue_position ni kuanzia 1, haijatajwa wakati si kwenye foleni)
  if (job.queue_position != null) console.log(`Nafasi foleni: ${job.queue_position}`)
}

GET /usage

Inahitaji Authorization: Bearer <api_key> (utafutaji wa kawaida wa ufunguo — si njia ya ndani ya kupita).

Inarudisha matumizi ya tokeni kwa mwezi wa kalenda wa sasa kwa mtumiaji aliyeidhinishwa.

Jibu 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 na tokens_remaining ni null kwa enterprise (ruzuku isiyo na kikomo katika ripoti).

Miundo ya maudhui

Thamani zinazotegemewa za format: plain, markdown, json, html.

RTL na mwelekeo katika programu yako

Kwa matokeo ya plain na markdown, API inarudisha tu maandishi yaliyotafsiriwa — haiongezi dir="rtl" au vipengele vya kufunika. Weka mwelekeo wa maandishi katika UI yako (CSS direction, sifa ya dir ya kipengele cha mzazi, au mpangilio wa i18n wa mfumo wako) wakati wa kuonyesha Kiarabu, Kiebrania, au Kifarsi.

Kwa muundo wa html, alama zilizotafsiriwa zinaweza kujumuisha dir="rtl" pale inapofaa kwa malengo ya RTL.

Majibu ya makosa

Makosa ni JSON inapowezekana:

{
  "error": "invalid_request",
  "message": "Maelezo yanayoweza kusomwa na binadamu"
}

GET /usage inaweza kurudisha 500 na ujumbe wa jumla ikiwa ombi la Supabase linashindwa.