REST API

Trois appels : envoyer un fichier, attendre, télécharger un ZIP. La clé va dans l'en-tête X-API-Key et est facultative.

1. Envoyer le fichier

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

Réponse

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

2. Interroger jusqu'à la fin

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

Réponse

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

3. Télécharger

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

Résultat

translations.zip avec de.json et ja.json. Le téléchargement reste disponible pendant environ une heure après la fin du travail.

Champs de POST /api/translate

Champ	Signification
`file`	Le fichier de langue. N'importe lequel des formats listés sous la ligne de commande.
`languages`	Codes séparés par des virgules, par exemple `de,ja`.
`verify`	`true` traduit chaque résultat en retour, pour vérifier le sens.
`glossary`	Mots séparés par des virgules à conserver tels quels.
`tone`	`formal` ou `casual`. Vide est neutre.
`icu`	`true` si les chaînes utilisent des pluriels ICU comme `{count, plural, …}`.
`app_context`	Une ligne sur l'application, jusqu'à 300 caractères.
`webhook_url`	Offre Team/API : une adresse https que nous appelons quand la tâche est terminée. Ci-dessous.

Tous les points d'accès

Point d'accès	Rôle
`POST /api/translate`	Démarre un travail, renvoie `job_id`.
`GET /api/status/{job_id}`	`pending`, `running`, `done` ou `error`, avec la progression.
`GET /api/preview/{job_id}`	Les traductions et les résultats de vérification sous forme de JSON.
`GET /api/download/{job_id}`	Le ZIP avec un fichier par langue.
`POST /api/v1/keys/request`	Émet une clé gratuite. Pas de corps, pas de compte.

Webhook à la fin d'un travail

Avec l'offre Team/API, envoyez webhook_url avec la tâche. Quand elle est terminée, nous envoyons ce JSON en POST à cette adresse. Votre texte traduit n'y figure jamais.

Corps

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

Vérifier que la requête vient de nous

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'en-tête X-Kaeris-Signature: sha256=<hex> est un HMAC-SHA256 du corps brut, créé avec le secret webhook de votre clé, qui n'est pas votre clé API. Obtenez-le sous le nom de webhook_secret à partir de GET /api/key/info avec votre clé dans X-API-Key ; il est également dans l'e-mail de votre clé. L'adresse doit être https et publique ; les adresses privées et locales sont refusées.

KAERIS a traduit cette page et vérifié chaque ligne en la retraduisant. Un locuteur natif ne l'a pas encore revue. Original anglais