Marejeo ya API

Hati hii inaendana na tabia ya programu ya Express katika api/app.js na wasimamizi wa njia chini ya api/routes/.

Mipaka na tabia

Kiasi cha tokeni kwa mwezi (ngazi ya bure): Kabla ya kuita mfano, 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 kiasi kilichobaki cha mwezi (FREE_TIER_MONTHLY_TOKENS, chaguo-msingi 100000). Ngazi za kulipwa hazizuiziwi na ukaguzi huu wa awali katika enforceTokenCap; matumizi bado yanarekodiwa.

Mipaka ya kiwango: Wakati Upstash Redis imewekwa (UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN, na URL haijumuishi sehemu ya your-instance), mipaka kwa dakika hutumika kwa ngazi: bure 5, mwanzo 30, ukuaji 60, kiwango 120, biashara haina kikomo. Ikiwa kikomo kinafikiwa, jibu ni 429 na error: "rate_limit_reached". Ikiwa Redis haijaanzishwa, ukomo wa kiwango unarukwa (angalia rateLimit.js).

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 36 rekodi; misimbo ndiyo thamani pekee zinazokubaliwa katika targets kwenye vituo vya kutafsiri.

Jibu 200

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

Chanzo: api/utils/languages.js.

POST /translate

Inahitaji Authorization: Bearer <api_key>.

Hutafsiri mfuatano mmoja wa content kwa kila lugha iliyoorodheshwa katika targets. Mfano hurudisha kitu kimoja cha JSON ambacho funguo zake ni hasa misimbo ya lugha iliyohitajika na thamani zake ni mfuatano wa maandishi yaliyotafsiriwa (angalia formatPrompts.js).

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 haijajumuishwa na utambuzi wa kiotomatiki umefanyika.

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>.

Hushughulikia kila kipengee mfululizo (mmoja kwa mmoja kwa kila kipengee). Ikiwa kipengee chochote kinashindwa, API hurudisha 500 na haitarudishi 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 hurudisha 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 endpoint hii badala ya POST /translate unapokuwa 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>.

Huchunguza hali ya kazi iliyotumwa kupitia POST /jobs. Fanya uchunguzi kila 5–10 sekunde. Kazi zinamilikiwa na mtumiaji aliyeituma — watumiaji wengine hupokea 404.

Jibu (inayosubiri / 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 zinazoingea au zinazochakata zilizotengenezwa kabla ya hii — tumia kwa UI ya maendeleo. Huitwa tu ikiwa ombi la kuhesabu halifanikiwa.

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, haitajumuishwa ikiwa haiko kwenye foleni)
  if (job.queue_position != null) console.log(`Nafasi foleni: ${job.queue_position}`)
}

GET /usage

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

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

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 (kiasi kisichokuwa 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 hurudisha maandishi yaliyotafsiriwa tu — 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; angalia formatPrompts.js na majaribio ya HTML katika scripts/test-translation.js.

Majibu ya makosa

Makosa ni JSON inapowezekana:

{
  "error": "invalid_request",
  "message": "Maelezo yanayosomeka na binadamu"
}

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

Mifano ya msingi (kwa taarifa)

API inaonyesha tu standard na advanced. Vitambulisho halisi vya mfano wa OpenAI vimewekwa katika api/utils/modelRouter.js na havirudishiwi katika majibu ya API.