API-viite

Täydellinen viite jokaiselle päätepisteelle, pyynnön ja vastauksen rakenteelle, virhekoodille ja nopeusrajoitukselle.

Rajat ja käyttäytyminen

Kuukausittainen token-rajoitus (ilmainen taso): Ennen mallin kutsumista API arvioi tokenit likimain ceil(content_length / 4) × (number_of_targets + 1) ja vain free-tasolla hylkää pyynnön 429 / token_limit_reached -virheellä, jos arvio ylittäisi jäljellä olevan kuukausittaisen määrän (oletus 100000). Maksullisia tasoja ei estetä tällä esitarkistuksella; käyttö kirjataan silti.

Nopeusrajoitukset: Kun Redis on konfiguroitu, minuutin rajoitukset pätevät tason mukaan: free 5, starter 30, growth 60, scale 120, enterprise rajoittamaton. Rajoituksen ylittyessä vastaus on 429 ja error: "rate_limit_reached". Jos Redis ei ole konfiguroitu, nopeusrajoitusta ei sovelleta.

Onnistuneissa nopeusrajoitetuissa vastauksissa voi olla mukana X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

GET /health

Ei todennusta.

Vastaus 200

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

GET /languages

Ei todennusta.

Palauttaa kanonisen listan tuetuista kielistä (koodi, näyttönimi, RTL-lippu). Merkintöjä on 43 — 36 peruskieltä ja 7 alueellista varianttia. Alueelliset variantit käyttävät BCP-47 aluealisiä alitunnisteita (esim. fr-CA, pt-BR, es-MX). Tämän päätepisteen koodit ovat ainoat hyväksytyt arvot targets-kentässä käännöspäätepisteillä.

Vastaus 200

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

Live-lista on myös saatavilla GET /languages -kutsulla — katso alla.

POST /translate

Vaatii Authorization: Bearer <api_key>.

Kääntää yksittäisen content-merkkijonon jokaiseen targets-listassa olevaan kieleen. Vastaus on yksittäinen JSON-objekti, jonka avaimet ovat täsmälleen pyydetyt kielikoodit ja arvot käännetyt merkkijonot.

Pyyntörunko

Vastaus 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 ja detection_confidence näkyvät vain, kun format on jätetty pois ja automaattinen tunnistus on suoritettu.

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

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

Vaatii Authorization: Bearer <api_key>.

Käsittelee jokaisen kohteen peräkkäin (yksi mallikutsu per kohde). Jos jokin kohde epäonnistuu, API palauttaa 500 eikä palauta osittaisia tuloksia kyseiselle pyynnölle.

Pyyntörunko

Vastaus 200

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

Esimerkki

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

Vaatii Authorization: Bearer <api_key>.

Lisää käännöstyön jonoon ja palauttaa välittömästi job_id:n. Käännös suoritetaan taustalla — ei HTTP-aikarajaa sisällön koosta riippumatta. Kysy tilaa GET /jobs/:id -päätepisteellä.

Käytä tätä päätepistettä POST /translate sijaan, kun käännät suuria dokumentteja (pitkä Markdown, monta kohdekieltä), joissa pyynnön kesto voi ylittää HTTP-asiakkaasi tai välityspalvelimesi aikarajan.

Pyyntörunko

Vastaus 202

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

GET /jobs/:id

Vaatii Authorization: Bearer <api_key>.

Kysyy tilaa POST /jobs -päätepisteellä lähetetylle työlle. Kysy tilaa 5–10 sekunnin välein. Työt kuuluvat lähettäneelle käyttäjälle — muut käyttäjät saavat 404.

Vastaus (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 on pending (odottaa työntekijää) tai processing (työntekijä on ottanut työn). queue_position (1-pohjainen) kertoo, kuinka monta odottavaa tai käsittelevää työtä on luotu tätä ennen — käytä sitä etenemisen näyttämiseen käyttöliittymässä. Jos laskentakysely epäonnistuu, se jätetään pois.

Vastaus (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"
  }
}

Vastaus (failed)

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

Esimerkki (JavaScript)

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

// 1. Lähetä
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. Kysy tilaa
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) }
  // Valinnainen: näytä eteneminen (queue_position on 1-pohjainen, jätetään pois jos ei jonossa)
  if (job.queue_position != null) console.log(`Jonon sijainti: ${job.queue_position}`)
}

GET /usage

Vaatii Authorization: Bearer <api_key> (tavallinen avaimen tarkistus — ei sisäinen ohituspolku).

Palauttaa token-käytön kuluvan kalenterikuukauden ajalta todennetulle käyttäjälle.

Vastaus 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 ja tokens_remaining ovat null arvolla enterprise (rajoittamaton myöntö raportoinnissa).

Sisältöformaatit

Tuetut format-arvot: plain, markdown, json, html.

RTL ja suunta sovelluksessasi

plain ja markdown-tulosteissa API palauttaa vain käännetyn tekstin — se ei lisää dir="rtl" tai kääre-elementtejä. Aseta tekstin suunta käyttöliittymässäsi (CSS:n direction, vanhemman elementin dir-attribuutti tai kehyskirjastosi i18n-asettelu) kun näytät arabiaa, hepreaa tai persiaa.

html-formaatissa käännetty merkintä voi sisältää dir="rtl" tarvittaessa RTL-kohteille.

Virhevastaukset

Virheet ovat JSON-muodossa, kun mahdollista:

{
  "error": "invalid_request",
  "message": "Ihmisen luettava yksityiskohta"
}

GET /usage voi palauttaa 500 yleisellä viestillä, jos Supabase-kysely epäonnistuu.