REST API

3 つの呼び出し: ファイルを送信し、待機し、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 が含まれます。ダウンロードは、ジョブ完了後約 1 時間利用可能です。

POST /api/translate のフィールド

フィールド	意味
`file`	言語ファイル。コマンドラインの下にリストされている形式のいずれか。
`languages`	カンマ区切りのコード。例: `de,ja`。
`verify`	`true` は、意味を確認するためにすべての結果を逆翻訳します。
`glossary`	そのままにしておく単語をカンマ区切りで指定します。
`tone`	`formal` または `casual`。空の場合は中立です。
`icu`	`true` は、文字列が ICU 複数形 (例: `{count, plural, …}`) を使用している場合です。
`app_context`	アプリに関する 1 行の説明。最大 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}`	言語ごとに 1 つのファイルが含まれる ZIP。
`POST /api/v1/keys/request`	無料キーを発行します。ボディもアカウントも不要です。

ジョブ完了時の Webhook

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 で、キーごとの Webhook シークレットで作成されます。このシークレットは API キーとは別物です。X-API-Key にキーを入れて GET /api/key/info を呼び出すと webhook_secret として取得できます。キーのメールにも記載されています。アドレスは https かつ公開されている必要があり、プライベートおよびローカルのアドレスは拒否されます。

KAERISはこのページを翻訳し、すべての行を逆翻訳して確認しました。ネイティブスピーカーによるレビューはまだ行われていません。英語原文