Rozpoczęcie

Użyj PolyLingo HTTP API do tłumaczenia zwykłego tekstu, Markdown, JSON lub HTML, zachowując strukturę. Ten przewodnik obejmuje punkt końcowy produkcji, uwierzytelnianie oraz twoje pierwsze udane żądanie.

Podstawowy URL

Wszystkie przykłady korzystają z produkcyjnego API:

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

Każda ścieżka poniżej jest względna względem tej bazy (na przykład POST /translate oznacza POST https://api.usepolylingo.com/v1/translate).

Jeśli uruchamiasz własną instancję PolyLingo API, zamień host na swój URL wdrożenia i zachowaj prefiks /v1, chyba że skonfigurowałeś inaczej.

Uwierzytelnianie

Chronione punkty końcowe oczekują twojego klucza API w nagłówku Authorization:

Authorization: Bearer <your_api_key>

Uzyskanie klucza: Utwórz go w aplikacji PolyLingo w sekcji API keys. Pełny klucz widzisz tylko raz — zapisz go w bezpiecznym miejscu (zmienna środowiskowa lub menedżer sekretów). Klucze można unieważnić z tego samego ekranu.

Bezpieczeństwo: Traktuj klucz jak hasło. Preferuj wywoływanie API z twojego serwera, a nie z publicznego kodu przeglądarki, aby klucz nigdy nie był ujawniony użytkownikom.

Jeśli nagłówek jest brakujący, błędny lub klucz jest nieważny albo unieważniony, API odpowiada kodem 401 i error: "invalid_api_key".

Punkty końcowe i klucze

Brak wymaganego kluczaGET /health — szybki test dostępności
GET /languages — obsługiwane kody języków
Wymagany kluczPOST /translate — tłumaczenie treści
POST /translate/batch — tłumaczenie wielu elementów
POST /jobs — umieszczenie długotrwałego tłumaczenia w kolejce (zwraca natychmiast 202)
GET /jobs/:id — sprawdzanie statusu zadania; zawiera queue_position podczas oczekiwania
GET /usage — użycie dla uwierzytelnionego konta

Pierwsze żądanie (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"
  }'

Udana odpowiedź zawiera obiekt translations (po jednej pozycji na każdy język docelowy, o który prosiłeś) oraz obiekt usage z liczbą tokenów.

Pierwsze żądanie (Node.js)

Node.js 18+ zawiera fetch:

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)

Sprawdź, czy API jest dostępne

Nie jest wymagany klucz do sprawdzenia stanu zdrowia:

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

Powinieneś zobaczyć mały ładunek JSON wskazujący, że usługa działa. Użyj GET /languages dla listy kodów, które możesz przekazać jako targets.

CORS i aplikacje przeglądarkowe

API może ograniczać, które pochodzenie przeglądarki może wywoływać je bezpośrednio, aby klucze nie były używane z nieznanych witryn. Wywołania po stronie serwera (Node, Python, funkcje edge, twój backend) nie są ograniczone przez CORS.

Dla aplikacji jednostronicowej zwykły wzorzec to: twój frontend komunikuje się z twoim backendem, a backend wywołuje PolyLingo z kluczem API.

Kolejne kroki

  • Dokumentacja API — kształty żądań i odpowiedzi, formaty, błędy i limity.
Pierwsze kroki | PolyLingo | PolyLingo