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-…

结果

包含 de.json 和 ja.json 的 translations.zip。下载在作业完成后约一小时内保持可用。

POST /api/translate 的字段

字段	含义
`file`	语言文件。可以是命令行下所列格式中的任何一种。
`languages`	逗号分隔的代码，例如 `de,ja`。
`verify`	`true` 会将所有结果翻译回来，以检查含义。
`glossary`	逗号分隔的单词，保持原样。
`tone`	`formal` 或 `casual`。留空表示中性。
`icu`	如果字符串使用 ICU 复数形式，如 `{count, plural, …}`，则为 `true`。
`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`	发放免费密钥。无请求体，无账户。

作业完成时的 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 密钥（secret）生成，它不是您的 API 密钥。在 X-API-Key 中带上您的密钥调用 GET /api/key/info，即可获取 webhook_secret；它也在发送密钥的邮件中。地址必须是 https 且可公开访问；私有地址和本地地址会被拒绝。

KAERIS 翻译了此页面，并通过回译检查了每一行。尚未经过母语人士审阅。英文原文