REST API

Tre chiamate: invia un file, attendi, scarica uno ZIP. La chiave va nell'intestazione X-API-Key ed è opzionale.

1. Invia il file

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

Risposta

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

2. Interroga finché non è pronto

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

Risposta

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

3. Scarica

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

Risultato

translations.zip con de.json e ja.json. Il download rimane disponibile per circa un'ora dopo il completamento del lavoro.

Campi di POST /api/translate

Campo	Significato
`file`	Il file di lingua. Qualsiasi dei formati elencati sotto la riga di comando.
`languages`	Codici separati da virgole, ad esempio `de,ja`.
`verify`	`true` ritraduce ogni risultato, per verificarne il significato.
`glossary`	Parole separate da virgole da mantenere così come sono scritte.
`tone`	`formal` o `casual`. Vuoto è neutro.
`icu`	`true` se le stringhe usano plurali ICU come `{count, plural, …}`.
`app_context`	Una riga sull'app, fino a 300 caratteri.
`webhook_url`	Piano Team/API: un indirizzo https che chiamiamo al termine del lavoro. Sotto.

Tutti gli endpoint

Endpoint	Cosa fa
`POST /api/translate`	Avvia un lavoro, restituisce `job_id`.
`GET /api/status/{job_id}`	`pending`, `running`, `done` o `error`, con progresso.
`GET /api/preview/{job_id}`	Le traduzioni e i risultati del controllo come JSON.
`GET /api/download/{job_id}`	Lo ZIP con un file per lingua.
`POST /api/v1/keys/request`	Emette una chiave gratuita. Nessun corpo, nessun account.

Webhook al termine di un lavoro

Con il piano Team/API, invia webhook_url insieme al lavoro. Al termine, inviamo questo JSON in POST a quell'indirizzo. Il tuo testo tradotto non è mai incluso.

Corpo

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

Verifica che provenga da noi

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 "")

L'intestazione X-Kaeris-Signature: sha256=<hex> è un HMAC-SHA256 del corpo grezzo, calcolato con il segreto webhook proprio della tua chiave, che non è la tua chiave API. Ottienilo come webhook_secret da GET /api/key/info con la tua chiave in X-API-Key; lo trovi anche nell'email con la chiave. L'indirizzo deve essere https e pubblico; gli indirizzi privati e locali vengono rifiutati.

KAERIS ha tradotto questa pagina e controllato ogni riga ritraducendola. Un madrelingua non l'ha ancora revisionata. Originale in inglese