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 次/时额度。打开账户页