Erste Schritte

Verwenden Sie die PolyLingo HTTP API, um Plaintext, Markdown, JSON oder HTML zu übersetzen und dabei die Struktur intakt zu halten. Diese Anleitung behandelt den Produktions-Endpunkt, die Authentifizierung und Ihre erste erfolgreiche Anfrage.

Basis-URL

Alle Beispiele verwenden die Produktions-API:

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

Jeder untenstehende Pfad ist relativ zu dieser Basis (zum Beispiel bedeutet POST /translate POST https://api.usepolylingo.com/v1/translate).

Wenn Sie Ihre eigene PolyLingo API-Instanz betreiben, ersetzen Sie den Host durch Ihre Deployment-URL und behalten Sie das Präfix /v1 bei, sofern Sie nichts anderes konfiguriert haben.

Authentifizierung

Geschützte Endpunkte erwarten Ihren API-Schlüssel im Authorization-Header:

Authorization: Bearer <your_api_key>

Einen Schlüssel erhalten: Erstellen Sie einen in der PolyLingo-App unter API keys. Den vollständigen Schlüssel sehen Sie nur einmal – speichern Sie ihn an einem sicheren Ort (Umgebungsvariable oder Secret Manager). Schlüssel können über denselben Bildschirm widerrufen werden.

Sicherheit: Behandeln Sie den Schlüssel wie ein Passwort. Rufen Sie die API vorzugsweise von Ihrem Server aus auf, nicht vom öffentlichen Browser-Code, damit der Schlüssel niemals für Benutzer sichtbar wird.

Wenn der Header fehlt, falsch ist oder der Schlüssel ungültig oder widerrufen wurde, antwortet die API mit 401 und error: "invalid_api_key".

Endpunkte und Schlüssel

Kein Schlüssel erforderlichGET /health — schnelle Verfügbarkeitsprüfung
GET /languages — unterstützte Sprachcodes
Schlüssel erforderlichPOST /translate — Inhalt übersetzen
POST /translate/batch — mehrere Elemente übersetzen
POST /jobs — lang laufende Übersetzung in die Warteschlange stellen (gibt sofort 202 zurück)
GET /jobs/:id — Jobstatus abfragen; enthält queue_position während des Wartens
GET /usage — Nutzung für das authentifizierte Konto

Erste Anfrage (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"
  }'

Eine erfolgreiche Antwort enthält ein translations-Objekt (ein Eintrag pro angeforderter Zielsprache) und ein usage-Objekt mit Token-Zählungen.

Erste Anfrage (Node.js)

Node.js 18+ enthält 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)

Prüfen, ob die API erreichbar ist

Für den Gesundheitscheck ist kein Schlüssel erforderlich:

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

Sie sollten eine kleine JSON-Antwort sehen, die anzeigt, dass der Dienst läuft. Verwenden Sie GET /languages für die Liste der Codes, die Sie als targets übergeben können.

CORS und Browser-Apps

Die API kann einschränken, welche Browser-Origins sie direkt aufrufen dürfen, damit Schlüssel nicht von nicht vertrauenswürdigen Seiten verwendet werden. Serverseitige Aufrufe (Node, Python, Edge-Funktionen, Ihr Backend) sind von CORS nicht eingeschränkt.

Für eine Single-Page-App ist das übliche Muster: Ihr Frontend kommuniziert mit Ihrem Backend, und Ihr Backend ruft PolyLingo mit dem API-Schlüssel auf.

Nächste Schritte

  • API reference — Anforderungs- und Antwortformate, Fehler und Limits.
Erste Schritte | PolyLingo | PolyLingo