REST API

輕湖翻譯 API

免費的中英互譯（Beta）。匿名 Playground 與 API Key 呼叫方共用同一套 JSON 契約，所有回應都是同一個信封 `{ code, message, data }`。

更新於 2026-11-08

快速開始

匿名翻譯（無需 Key；按 IP 計額 10 次/時）：

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

帶 API Key 翻譯（按使用者計額 100 次/時）：

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

驗證

呼叫方	端點	憑證	計額
匿名 Playground	`POST /api/public/translate`	無（按 IP 限流）	按 IP：10 次/時 + 5 次/分
API Key	`POST /api/open/translate`	`X-API-Key: ltr_{env}_{32hex}` 請求標頭	Key 所屬使用者：100 次/時 + 20 次/分

Key 在帳戶頁簽發（每使用者 3 把 active），明文只顯示一次。被撤銷或未知的 Key 一律回傳 401 + code 40101——API 絕不降級為匿名存取。

端點

POST /api/open/translate

資料面翻譯端點。

請求主體：

欄位	型別	說明
`text`	`string`	要翻譯的文字。1–5000 字元；超長回傳 `40021`。
`source`	`zh` / `en` / `auto`	來源語言。預設 `auto`（漢字佔比 ≥ 30% 判定為 `zh`）。
`target`	`zh` / `en`	目標語言。必填；明確指定 `source` 時必須不同（否則 `40022`）。
`format`	`text` / `markdown`	輸出模式。預設 `text`，見下方 Markdown 模式。

回應 data：

欄位	型別	說明
`translation`	`string`	譯文。
`detected_source`	`zh` / `en`	`source=auto` 時的偵測結論。
`char_count`	`number`	輸入字元數。
`format`	`text` / `markdown`	回顯請求的 format。
`usage`	`object`	`{ channel, used_this_hour, limit_this_hour, reset_at }`——本次呼叫後的額度快照。

GET /api/open/languages

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

GET /api/open/usage

目前 Key 的額度快照：{ channel, used_this_hour, limit_this_hour, remaining_this_hour, reset_at, tier, key_prefix }。超級 Key（ltrs_ 前綴）回傳 limit_this_hour: 0 表示不限。

GET /api/public/info

產品資訊 + 目前 IP 的匿名額度狀態（Playground 用）。

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

登入使用者用量（工作階段 cookie）：{ window, used, limit, remaining, reset_at }。hour 在整點重置；day 按自然日分桶，Beta 期不限量（limit: 0）。

限流標頭

每次翻譯回應都帶有：

標頭	含義
`X-RateLimit-Limit`	本次呼叫的額度桶大小（使用者 100 / 匿名 10）。
`X-RateLimit-Remaining`	目前小時窗剩餘次數。
`X-RateLimit-Reset`	窗口重置的 Unix 時間。
`Retry-After`	需等待的秒數——僅 `429` 回應帶有。

Markdown 模式

傳 "format": "markdown" 保持文件結構。伺服器在譯前譯後清點圍欄程式碼區塊（```/~~~）、連結 [text](url) 與圖片 ![alt](url) 的數量；數量漂移會自動重試一次，仍不一致則回傳 500 / 50023 且不計次——該輸入請改用 text。

計次規則

只有成功的翻譯計次。參數錯誤（400xx）、驗證失敗、上游錯誤（50021/50022）、Markdown 結構拒絕（50023）與儲存不可用（50024）一律不扣額度。

錯誤碼

HTTP	Code	含義	處置
400	40001	參數無效	檢查必填欄位（`text`、`target`）與 `format` 取值。
400	40021	文字超長	按 5000 字元拆分輸入。
400	40022	語言不支援	僅中↔英；`source` 與 `target` 不能相同。
401	40101	Key 無效/已撤銷/已過期	到帳戶頁重新簽發。
401	40102	未登入	`/api/user/*` 端點需要 UC 工作階段。
403	40301	使用者被封禁	透過聯絡頁回饋。
429	42901	配額超限	等待 `Retry-After` 秒；重置時間見回應標頭。
500	50021	上游錯誤	退避重試；本次呼叫未計次。
504	50022	上游逾時（180s）	縮短文字重試；本次呼叫未計次。
500	50023	Markdown 結構驗證失敗	改用 `format: "text"`；本次呼叫未計次。
503	50024	額度儲存不可用	fail-closed 保護——稍後重試。

Agent Skill

想要命令列？到 Skill 頁安裝 Agent Skill——同一套錯誤碼封裝了本 API，並自帶離線自我檢查。

領取 API Key

登入後在帳戶頁免費簽發——Key 繼承你的 100 次/時額度。開啟帳戶頁