REST API

Tres llamadas: enviar un archivo, esperar, descargar un ZIP. La clave va en la cabecera X-API-Key y es opcional.

1. Envía el archivo

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

Respuesta

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

2. Consulta hasta que termine

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

Respuesta

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

3. Descarga

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

Resultado

translations.zip con de.json y ja.json. La descarga permanece disponible durante aproximadamente una hora después de que finaliza el trabajo.

Campos de POST /api/translate

Campo	Significado
`file`	El archivo de idioma. Cualquiera de los formatos listados bajo la línea de comandos.
`languages`	Códigos separados por comas, por ejemplo `de,ja`.
`verify`	`true` traduce cada resultado de vuelta, para comprobar el significado.
`glossary`	Palabras separadas por comas para mantener tal cual.
`tone`	`formal` o `casual`. Vacío es neutral.
`icu`	`true` si las cadenas usan plurales de ICU como `{count, plural, …}`.
`app_context`	Una línea sobre la aplicación, hasta 300 caracteres.
`webhook_url`	Plan Team/API: una dirección https a la que llamamos cuando finaliza el trabajo. Abajo.

Todos los endpoints

Endpoint	Lo que hace
`POST /api/translate`	Inicia un trabajo, devuelve `job_id`.
`GET /api/status/{job_id}`	`pending`, `running`, `done` o `error`, con progreso.
`GET /api/preview/{job_id}`	Las traducciones y los resultados de la comprobación como JSON.
`GET /api/download/{job_id}`	El ZIP con un archivo por idioma.
`POST /api/v1/keys/request`	Emite una clave gratuita. Sin cuerpo, sin cuenta.

Webhook cuando finaliza un trabajo

En el plan Team/API, envía webhook_url con el trabajo. Cuando termina, enviamos este JSON por POST a esa dirección. Tu texto traducido nunca va en él.

Cuerpo

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

Comprueba que vino de nosotros

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

La cabecera X-Kaeris-Signature: sha256=<hex> es un HMAC-SHA256 del cuerpo sin procesar, hecho con el secreto webhook de tu clave, que no es tu clave API. Obténlo como webhook_secret de GET /api/key/info con tu clave en X-API-Key; también está en el correo de tu clave. La dirección debe ser https y pública; se rechazan direcciones privadas y locales.

KAERIS ha traducido esta página y revisado cada línea traduciéndola de vuelta. Un hablante nativo aún no la ha revisado. Original en inglés