API

Endpoints

Auth + rate limits

The browser UI needs no signup. Direct API access may require a partner key when spend protection is enabled; otherwise anonymous traffic is limited per client IP. Expensive endpoints are metered more tightly:

• /api/translate: 15 req/min, 150 req/hour
• /api/speak: 10 req/min, 60 req/hour (audio is the most expensive to generate)
• /api/variants: 10 req/min, 80 req/hour
• /api/lookup and /api/lint: 60 req/min, 600 req/hour

Requests are capped at 20,000 characters of input. Respect Retry-After on a 429 and back off rather than retrying immediately.

Partner API keys raise /api/translate to 60 req/min and 2,000 req/hour, and rate-limit per key instead of per IP. Pass the key in the X-API-Key header:

curl https://translate.tetumdili.com/api/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${TETUN_API_KEY}" \
  -d '{"text":"Good morning, how are you?","sourceLang":"en","targetLang":"tet"}'

Keys are issued case-by-case for partners running document-mode or batch workflows. Include a short description of what you’re building. Free for community / nonprofit / Timor-Leste government use.

Request a key — [email protected]

Request body

/api/translate accepts these fields. Source/target languages can be passed as sourceLang + targetLang or as the shorthand direction: "en-to-tet" / "tet-to-en". When both language fields are supplied they must differ, one side must be Tetun or Fataluku, and they take precedence over the legacy direction field.

{
  "text": "string (1–20,000 chars, required)",
  "sourceLang": "auto | en | tet | ftl | id | pt | ko | zh | ja | vi | fr | es | de | it | nl | ar | tl",
  "targetLang": "en | tet | ftl | id | pt | ko | zh | ja | vi | fr | es | de | it | nl | ar | tl",
  "direction": "en-to-tet | tet-to-en",
  "ortho": "auto | dit | inl",
  "register": "formal | neutral | casual",
  "domain": "general | justice | health | tourism_food | government",
  "quality": true,
  "private": false,
  "fresh": false,
  "terminologyHints": ["BNNTD", "MPRM", "Teodoro Vieira Lemos"]
}

• quality: true enables Careful mode’s independent verify/revise pass for signed browser sessions or API-key callers.
• fresh: true bypasses a prior response-cache hit for signed browser sessions or API-key callers, while still caching the new verified result.
• private: true bypasses the response cache and omits source and result text from translation audit records. Technical request metadata is still retained and the text is still processed to translate it.

Response stream

The translate endpoint returns a newline-delimited stream of JSON events. Read until you receive a done event and use its text field as the canonical result. Chunk events are presentation-only; a revision replaces all prior chunks. If the connection closes before done, treat the request as failed and never persist the partial text.

{"type":"meta","requestId":"...","sourceLang":"en","targetLang":"tet","ortho":"dit"}
{"type":"glossary","matches":[{"en":"...","tet":"..."}]}
{"type":"corpus","matches":[{"en":"...","tet":"..."}]}
{"type":"phase","phase":"drafting","label":"Drafting translation…"}
{"type":"chunk","text":"Bondia,"}
{"type":"chunk","text":" Ita diak ka lae?"}
{"type":"revision","text":"Bondia. Ita diak ka lae?","reason":"lint-repair"}
{"type":"done","text":"Bondia. Ita diak ka lae?","meta":{"servedBy":"model","repairApplied":true}}

Errors

• 400 — missing or invalid input
• 429 — rate limited (check Retry-After)
• 500 — server misconfigured (rare)
• 502 — upstream translation backend error

Integrations

A Microsoft Word add-in for translating selected text in place is in early development at /word-addin — install via Office sideloading; AppSource distribution comes once it’s field-tested.

Terms & data

Use of the API is subject to our Terms of Use and Privacy Policy. In short: stay within the rate limits, don’t present the API as your own translation service, don’t use the speech endpoint to imitate a real person, and attribute Tetun Translator where results are shown to end users. Translations are grounded in third-party dictionaries and corpora that remain the property of their authors — the API grants no rights in that underlying data.