REST API

Drei Aufrufe: Datei senden, warten, ZIP herunterladen. Der Schlüssel steht im Header X-API-Key und ist optional.

1. Datei senden

curl -X POST https://kaeris.dev/api/translate \
  -H "X-API-Key: $KAERIS_API_KEY" \
  -F "[email protected]" \
  -F "languages=de,ja"

Antwort

{ "job_id": "3f8a2c1d-…", "edit_token": "…" }

2. Abfragen, bis es fertig ist

curl https://kaeris.dev/api/status/3f8a2c1d-…

Antwort

{ "status": "done", "progress": 2, "total": 2, "error": "",
  "current_lang": "ja", "failed_langs": [] }

3. Herunterladen

curl -o translations.zip https://kaeris.dev/api/download/3f8a2c1d-…

Ergebnis

translations.zip mit de.json und ja.json. Der Download bleibt etwa eine Stunde nach Abschluss des Auftrags verfügbar.

Felder von POST /api/translate

Feld	Bedeutung
`file`	Die Sprachdatei. Jedes der unter Kommandozeile aufgeführten Formate.
`languages`	Kommagetrennte Codes, zum Beispiel `de,ja`.
`verify`	`true` übersetzt jedes Ergebnis zurück, um die Bedeutung zu überprüfen.
`glossary`	Kommagetrennte Wörter, die unverändert bleiben sollen.
`tone`	`formal` oder `casual`. Leer ist neutral.
`icu`	`true`, wenn die Zeichenfolgen ICU-Pluralformen wie `{count, plural, …}` verwenden.
`app_context`	Eine Zeile über die App, bis zu 300 Zeichen.
`webhook_url`	Tarif Team/API: eine https-Adresse, die wir aufrufen, wenn der Auftrag fertig ist. Unten.

Alle Endpunkte

Endpunkt	Was er macht
`POST /api/translate`	Startet einen Auftrag, gibt `job_id` zurück.
`GET /api/status/{job_id}`	`pending`, `running`, `done` oder `error`, mit Fortschritt.
`GET /api/preview/{job_id}`	Die Übersetzungen und die Prüfergebnisse als JSON.
`GET /api/download/{job_id}`	Das ZIP mit einer Datei pro Sprache.
`POST /api/v1/keys/request`	Gibt einen kostenlosen Schlüssel aus. Kein Body, kein Konto.

Webhook, wenn ein Auftrag abgeschlossen ist

Im Tarif Team/API senden Sie webhook_url mit dem Auftrag. Ist er fertig, senden wir dieses JSON per POST an die Adresse. Ihr übersetzter Text ist nie enthalten.

Body

{
  "event": "translation.completed",
  "job_id": "3f8a2c1d-…",
  "status": "done",
  "languages": ["de", "ja"],
  "failed_languages": [],
  "source_chars": 1840,
  "download_url": "https://kaeris.dev/api/download/3f8a2c1d-…"
}

Prüfen, ob die Anfrage von uns kommt

import hashlib, hmac

# secret: "webhook_secret" from GET /api/key/info (X-API-Key: your key)
def is_from_kaeris(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body,
                                    hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

Der Header X-Kaeris-Signature: sha256=<hex> ist ein HMAC-SHA256 des rohen Bodys, erstellt mit dem Webhook-Geheimnis Ihres Schlüssels, das nicht Ihr API-Schlüssel ist. Holen Sie es als webhook_secret von GET /api/key/info mit Ihrem Schlüssel in X-API-Key; es ist auch in Ihrer Schlüssel-E-Mail enthalten. Die Adresse muss https und öffentlich sein; private und lokale Adressen werden abgelehnt.

KAERIS hat diese Seite übersetzt und jede Zeile durch Rückübersetzung geprüft. Ein Muttersprachler hat sie noch nicht überprüft. Englisches Original