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 używają 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ń hosta na swój adres 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ć na tym samym ekranie.

Bezpieczeństwo: Traktuj klucz jak hasło. Zaleca się wywoływanie API z poziomu 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

Nie wymaga kluczaGET /health — szybki test dostępności
GET /languages — obsługiwane kody języków
Wymaga kluczaPOST /translate — tłumaczenie treści
POST /translate/batch — tłumaczenie wielu elementów
POST /jobs — dodanie długotrwałego tłumaczenia do kolejki (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"
  }'

Pomyślna odpowiedź zawiera obiekt translations (pozycja na każdy żądany język docelowy) 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 źródła przeglądarki mogą 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: frontend komunikuje się z backendem, a backend wywołuje PolyLingo z kluczem API.

Kolejne kroki

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