Aloittaminen

Käytä PolyLingo HTTP API:a kääntääksesi pelkkää tekstiä, Markdownia, JSONia tai HTML:ää säilyttäen rakenteen ehjänä. Tämä opas kattaa tuotantopäätepisteen, autentikoinnin ja ensimmäisen onnistuneen pyynnön.

Perus-URL

Kaikki esimerkit käyttävät tuotanto-API:a:

URL
Tuotantohttps://api.usepolylingo.com/v1

Jokainen alla oleva polku on suhteessa tähän perusosoitteeseen (esimerkiksi POST /translate tarkoittaa POST https://api.usepolylingo.com/v1/translate).

Jos käytät omaasi PolyLingo API -instanssia, vaihda isäntä oman käyttöönotto-URL:si mukaiseksi ja pidä /v1-etuliite, ellei toisin ole määritetty.

Autentikointi

Suojaetapit odottavat API-avaintasi Authorization-otsikossa:

Authorization: Bearer <your_api_key>

Avain saaminen: Luo avain PolyLingo-sovelluksessa kohdassa API keys. Näet koko avaimen vain kerran—tallenna se turvalliseen paikkaan (ympäristömuuttujaan tai salaisuuksien hallintaan). Avaimia voi peruuttaa samalta näytöltä.

Turvallisuus: Kohtele avainta kuin salasanaa. Suosi API-kutsuja palvelimeltasi, älä julkisesta selainkoodista, jotta avain ei koskaan paljastu käyttäjille.

Jos otsikko puuttuu, on väärä tai avain on virheellinen tai peruutettu, API vastaa 401-koodilla ja error: "invalid_api_key".

Päätepisteet ja avaimet

Ei vaadi avaintaGET /health — nopea palvelun tilan tarkistus
GET /languages — tuetut kielikoodit
Vaatii avaimenPOST /translate — sisällön kääntäminen
POST /translate/batch — useiden kohteiden kääntäminen
POST /jobs — pitkän käännöstyön jonoon laittaminen (palauttaa 202 heti)
GET /jobs/:id — työn tilan kysely; sisältää queue_position odotuksen aikana
GET /usage — käytön tiedot todennetulle tilille

Ensimmäinen pyyntö (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

Onnistunut vastaus sisältää translations-objektin (yksi merkintä kutakin pyytämääsi kohdekieltä kohti) ja usage-objektin, jossa on token-laskurit.

Ensimmäinen pyyntö (Node.js)

Node.js 18+ sisältää fetch-toiminnon:

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

Tarkista, että API on saavutettavissa

Terveystarkistukseen ei tarvita avainta:

curl -sS "https://api.usepolylingo.com/v1/health"

Näet pienen JSON-vastauksen, joka osoittaa palvelun olevan toiminnassa. Käytä GET /languages saadaksesi listan koodeista, joita voit käyttää targets-kentässä.

CORS ja selainapplikaatiot

API saattaa rajoittaa, mitkä selaimen alkuperät voivat kutsua sitä suoraan, jotta avaimia ei käytetä epäluotettavilta sivustoilta. Palvelinpuolen kutsut (Node, Python, edge-funktiot, backendisi) eivät ole CORS-rajoitusten alaisia.

Yhden sivun sovelluksessa tavallinen malli on: frontendisi kommunikoi backendisi kanssa, ja backend kutsuu PolyLingoa API-avaimella.

Seuraavat askeleet

  • API reference — pyyntö- ja vastausrakenteet, muodot, virheet ja rajat.
Aloittaminen | PolyLingo | PolyLingo