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 и проверил каждую строку обратным переводом. Носитель языка ещё не проверял. Оригинал на английском