REST API

LiteTranslate API

Free Chinese ↔ English translation (Beta). One JSON contract for the anonymous Playground and API-key callers; every response uses the same envelope `{ code, message, data }`.

Updated 2026-11-08

Quick start

Translate anonymously (no key; per-IP quota 10/hour):

curl -X POST https://translate.litelake.com/api/public/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，世界","source":"auto","target":"en"}'

Translate with an API key (per-user quota 100/hour):

curl -X POST https://translate.litelake.com/api/open/translate \
  -H "X-API-Key: ltr_prod_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好，世界","source":"auto","target":"en","format":"text"}'

Authentication

Caller	Endpoint	Credential	Quota counted
Anonymous Playground	`POST /api/public/translate`	none (rate-limited per IP)	per IP: 10/hour + 5/minute
API key	`POST /api/open/translate`	`X-API-Key: ltr_{env}_{32hex}` header	key owner: 100/hour + 20/minute

Keys are issued on the Account page (3 active per user) and shown once. A revoked or unknown key always returns 401 with code 40101 — the API never degrades to anonymous access.

Endpoints

POST /api/open/translate

The data-plane translation endpoint.

Request body:

Field	Type	Description
`text`	`string`	Text to translate. 1–5000 characters; longer input → `40021`.
`source`	`zh` / `en` / `auto`	Source language. Default `auto` (CJK ratio ≥ 30% → `zh`).
`target`	`zh` / `en`	Target language. Required; must differ from an explicit `source` (else `40022`).
`format`	`text` / `markdown`	Output mode. Default `text`. See Markdown mode below.

Response data:

Field	Type	Description
`translation`	`string`	The translated text.
`detected_source`	`zh` / `en`	Result of detection when `source=auto`.
`char_count`	`number`	Character count of the input.
`format`	`text` / `markdown`	Echo of the requested format.
`usage`	`object`	`{ channel, used_this_hour, limit_this_hour, reset_at }` — quota snapshot after this call.

GET /api/open/languages

{ "languages": [{ "code": "zh" }, { "code": "en" }], "formats": ["text", "markdown"] }

GET /api/open/usage

Quota snapshot for the calling key: { channel, used_this_hour, limit_this_hour, remaining_this_hour, reset_at, tier, key_prefix }. Super keys (ltrs_ prefix) return limit_this_hour: 0 meaning unlimited.

GET /api/public/info

Product info plus the current IP's anonymous quota status (Playground use).

GET /api/user/usage?window=hour|day

Signed-in user usage (session cookie): { window, used, limit, remaining, reset_at }. hour resets on the hour; day is calendar-day bucketed and uncapped in Beta (limit: 0).

Rate-limit headers

Every translation response carries:

Header	Meaning
`X-RateLimit-Limit`	Quota bucket size for this call (100 user / 10 anonymous).
`X-RateLimit-Remaining`	Calls left in the current hourly window.
`X-RateLimit-Reset`	Unix time when the window resets.
`Retry-After`	Seconds to wait — present on `429` responses only.

Markdown mode

Set "format": "markdown" to preserve document structure. The server counts fenced code blocks (```/~~~), links [text](url) and images ![alt](url) before and after translation. If counts drift, it retries once; if the structure still does not match, it returns 500 / 50023 and does not count the call — switch to text for that input.

Counting rules

Only successful translations are counted. Parameter errors (400xx), auth failures, upstream errors (50021/50022), Markdown structure rejections (50023) and storage-unavailable responses (50024) are free of charge.

Error codes

HTTP	Code	Meaning	What to do
400	40001	Invalid parameters	Check required fields (`text`, `target`) and `format` value.
400	40021	Text too long	Split the input at 5000 characters.
400	40022	Unsupported language pair	Only Chinese ↔ English; `source` must differ from `target`.
401	40101	API key invalid / revoked / expired	Issue a new key on the Account page.
401	40102	Not signed in	The `/api/user/*` endpoint needs a UC session.
403	40301	User banned	Contact support via the Contact page.
429	42901	Quota exceeded	Wait for `Retry-After` seconds; reset times are in the headers.
500	50021	Upstream error	Retry with backoff; the call was not counted.
504	50022	Upstream timeout (180s)	Retry with a shorter text; the call was not counted.
500	50023	Markdown structure check failed	Use `format: "text"`; the call was not counted.
503	50024	Quota storage unavailable	Fail-closed protection — retry in a moment.

Agent Skill

Prefer a CLI? Install the Agent Skill from the Skill page — it wraps this API with the same error codes and adds an offline self-check.