Tarjumi API (v1)

Base URL: https://tarjumi.thexi.dev

Authentication

All /v1/* endpoints require an API key:

x-api-key: trj_live_…

(Authorization: Bearer trj_live_… also accepted.) /health is open.

Errors use a uniform contract:

{ "error": { "code": "unauthorized", "message": "Missing API key", "request_id": "…" } }

401 invalid/missing key · 429 rate-limit or quota exceeded (with Retry-After) · 400 bad request.

Rate limits

Per key: a per-minute rate (token bucket) and a daily quota. Response headers include x-ratelimit-remaining. Limits are set per plan when the key is issued.

Endpoints

POST /v1/translate

{ "text": "Take this medicine twice a day", "target_lang": "sw", "source_lang": "en" }

→

{ "translation": "Chukua dawa hii mara mbili kwa siku", "target_lang": "sw",
  "target_lang_name": "Swahili (Kiswahili)", "model": "nllb-200-ct2", "tarjumi_version": "v8f" }

source_lang optional (auto-detected if omitted).

POST /v1/i18n/bundle

Batch key→text translation for localization:

{ "target_lang": "ki", "strings": { "welcome": "Welcome", "submit": "Submit" } }

POST /v1/translate-document

Multipart upload (PDF/DOCX/TXT) → translated document.

GET /health

Open. Returns {status, version, languages}.

Languages

High quality: sw, ki, luo, kam, so, am, yo, zu, rw, lg, …. Full list: GET /v1/i18n/languages. Quality is strongest for low-resource × specialized (e.g. health) text — see EVALUATION.md.

Example

curl -X POST https://tarjumi.thexi.dev/v1/translate \
  -H "x-api-key: $TARJUMI_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Wash your hands to prevent disease","target_lang":"lg"}'

The machine-readable spec is worker/openapi.yaml (rendered at docs.thexi.dev).