# 云端 API 参考

鉴权、请求结构和明确的失败处理。

## 翻译接口 [#翻译接口]

`POST /api/platform/v1/translate`

服务端使用 Bearer API Key。需要项目的云端服务授权有效，且平台已配置真实推理上游。

```bash
curl "$ELEJO_API_URL/api/platform/v1/translate" \
  -H "Authorization: Bearer $ELEJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"你好","source":"zh","target":"en"}'
```

## 参数 [#参数]

| 字段   | 类型   | 限制                       |
| ------ | ------ | -------------------------- |
| text   | string | 去除首尾空白后 1–5000 字符 |
| source | string | 2–3 位小写语言代码         |
| target | string | 2–3 位小写语言代码         |

成功响应包含 `translation` 字符串。实际语种支持由上游决定。当前网关每个 Key 每分钟最多接受 30 次请求；此限制不代替企业配额或账务。

## 错误与重试 [#错误与重试]

400 输入无效；401 Key 无效；403 未开通或授权失效；429 请求过多；502 上游错误；503 未配置服务；504 上游连接超时。请使用带随机抖动的退避重试，仅重试临时错误，避免无限重试。

## 密钥生命周期 [#密钥生命周期]

Key 明文只显示一次。平台保存哈希与前缀。轮换时先创建新 Key，在服务端替换配置并验证，再撤销旧 Key。不要在浏览器、移动 App 安装包或公开仓库嵌入长期 Key。

[下载 OpenAPI 契约](/openapi.json)
