REST API

Три виклики: надіслати файл, зачекати, завантажити ZIP. Ключ передається в заголовку X-API-Key і є необов'язковим.

1. Надіслати файл

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

Відповідь

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

2. Опитувати до готовності

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

Відповідь

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

3. Завантажити результат

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

Результат

translations.zip з de.json та ja.json. Завантажити його можна приблизно протягом години після завершення завдання.

Поля POST /api/translate

Поле	Значення
`file`	Мовний файл. Будь-який із форматів, перелічених у розділі про командний рядок.
`languages`	Коди, розділені комою, наприклад `de,ja`.
`verify`	`true` перекладає кожен результат назад, щоб перевірити зміст.
`glossary`	Слова, розділені комою, які слід залишити як є.
`tone`	`formal` або `casual`. Порожнє означає нейтральне.
`icu`	`true`, якщо рядки використовують форми множини ICU на зразок `{count, plural, …}`.
`app_context`	Один рядок про додаток, до 300 символів.
`webhook_url`	Тариф Team/API: https-адреса, яку ми викликаємо після завершення завдання. Нижче.

Усі ендпоінти

Ендпоінт	Що робить
`POST /api/translate`	Запускає завдання, повертає `job_id`.
`GET /api/status/{job_id}`	`pending`, `running`, `done` або `error`, з прогресом.
`GET /api/preview/{job_id}`	Переклади та результати перевірки у форматі JSON.
`GET /api/download/{job_id}`	ZIP з одним файлом на мову.
`POST /api/v1/keys/request`	Видає безкоштовний ключ. Без тіла, без облікового запису.

Вебхук після завершення завдання

На тарифі Team/API передайте webhook_url разом із завданням. Коли воно завершиться, ми надішлемо цей JSON методом POST на цю адресу. Перекладеного тексту в ньому немає.

Тіло

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

Перевірка, що запит від нас

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

Заголовок X-Kaeris-Signature: sha256=<hex> — це HMAC-SHA256 від сирого тіла запиту, обчислений із власним секретом вебхука вашого ключа; це не ваш ключ API. Отримайте його як webhook_secret з GET /api/key/info з вашим ключем у X-API-Key; він також є в листі з ключем. Адреса має бути https і публічною; приватні та локальні адреси відхиляються.

KAERIS переклав цю сторінку та перевірив кожен рядок зворотним перекладом. Носій мови ще не переглядав її. Оригінал англійською