REST API

Três chamadas: enviar um arquivo, esperar, baixar um ZIP. A chave vai no cabeçalho X-API-Key e é opcional.

1. Enviar o arquivo

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

Resposta

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

2. Consultar até terminar

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

Resposta

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

3. Baixar

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

Resultado

translations.zip com de.json e ja.json. O download permanece disponível por cerca de uma hora após a conclusão do trabalho.

Campos de POST /api/translate

Campo	Significado
`file`	O arquivo de idioma. Qualquer um dos formatos listados na linha de comando.
`languages`	Códigos separados por vírgula, por exemplo `de,ja`.
`verify`	`true` traduz cada resultado de volta, para verificar o significado.
`glossary`	Palavras separadas por vírgula para manter como estão escritas.
`tone`	`formal` ou `casual`. Vazio é neutro.
`icu`	`true` se as strings usam plurais ICU como `{count, plural, …}`.
`app_context`	Uma linha sobre o aplicativo, até 300 caracteres.
`webhook_url`	Plano Team/API: um endereço https que chamamos quando o trabalho termina. Abaixo.

Todos os endpoints

Endpoint	O que faz
`POST /api/translate`	Inicia um trabalho, retorna `job_id`.
`GET /api/status/{job_id}`	`pending`, `running`, `done` ou `error`, com progresso.
`GET /api/preview/{job_id}`	As traduções e os resultados da verificação como JSON.
`GET /api/download/{job_id}`	O ZIP com um arquivo por idioma.
`POST /api/v1/keys/request`	Emite uma chave gratuita. Sem corpo, sem conta.

Webhook quando um trabalho termina

No plano Team/API, envie webhook_url com o trabalho. Quando ele terminar, enviamos este JSON por POST para esse endereço. Seu texto traduzido nunca vai nele.

Corpo

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

Verifique se veio de nós

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

O cabeçalho X-Kaeris-Signature: sha256=<hex> é um HMAC-SHA256 do corpo bruto, feito com o próprio segredo de webhook da sua chave, que não é sua chave de API. Obtenha-o como webhook_secret de GET /api/key/info com sua chave em X-API-Key; ele também está no e-mail da sua chave. O endereço deve ser https e público; endereços privados e locais são recusados.

KAERIS traduziu esta página e verificou cada linha traduzindo-a de volta. Um falante nativo ainda não revisou. Original em inglês