桌面端 Local API — PrivyTranslate

概览

在 PrivyTranslate 设置中启用 Local API。服务随后只在回环接口上监听——别的机器无法访问，任何请求也不会被转发到别处。

基础 URLhttp://127.0.0.1:49321/v1

API 版本v1

平台macOS

内容类型application/json

下载 OpenAPI JSON ↓

身份验证

启用 Local API 后，设置界面会显示一个 API 令牌。除 /health 和 /capabilities 之外的所有接口都需要它。支持三种传递方式：

X-Privy-Token 请求头——HTTP 请求的主要形式。
Authorization: Bearer——HTTP 请求和 WebSocket 握手都接受。
?token= 或 ?access_token=——供无法设置请求头的浏览器 WebSocket 客户端使用的查询参数。

请把令牌当作任何其他凭据来对待：谁持有它，谁就能在你的机器上发起翻译。

接口列表

GET /health 服务健康状况与就绪状态公开 GET /capabilities 引擎、语言、功能与限制公开 POST /translate 翻译一条或多条文本需令牌 POST /detect 检测每一条内容的语种需令牌 GET /ws/translate 通过 WebSocket 进行流式翻译需令牌

翻译

POST /translate 接收最多 128 条字符串，并按原顺序为每一条返回一个结果。source 默认为 auto；target 为必填。

请求

curl

curl -s http://127.0.0.1:49321/v1/translate \
  -H "X-Privy-Token: $PRIVY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "auto",
    "target": "zh-Hans",
    "texts": ["Could you confirm the revised delivery schedule?"],
    "mode": "paragraph",
    "format": "text",
    "options": { "engine": "auto", "sensitive": true }
  }'

mode 可取 selection、paragraph、webpage、subtitle、message 或 document。format 可取 text、html 或 markdown。在 options 中，engine 用于指定具体后端（local-llm、ollama、lm-studio、openai-compatible），sensitive: true 则让该请求不进入翻译历史。

响应

200 · application/json

{
  "id": "tr_8F2A6D4E-5F58-4A37-8E92-7B4FD40BE2D2",
  "object": "translation",
  "created": 1755561600,
  "engine": "local-llm",
  "model": "translategemma-4b-it.Q4_K_M.gguf",
  "source": "en",
  "target": "zh-Hans",
  "results": [
    {
      "index": 0,
      "text": "能否确认修订后的交付时间表？",
      "detected_source": "en",
      "confidence": 0.98,
      "alternatives": []
    }
  ],
  "usage": { "input_chars": 48, "output_chars": 15, "latency_ms": 412 }
}

语种检测

POST /detect 不做翻译，只为每一条内容返回一个语言代码和一个 0 到 1 之间的置信度分数。

curl

curl -s http://127.0.0.1:49321/v1/detect \
  -H "Authorization: Bearer $PRIVY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "texts": ["Guten Morgen", "早上好"] }'

200 · application/json

{
  "id": "det_8F2A6D4E-5F58-4A37-8E92-7B4FD40BE2D2",
  "object": "language_detection",
  "created": 1755561600,
  "results": [
    { "index": 0, "language": "de", "confidence": 0.97 },
    { "index": 1, "language": "zh-Hans", "confidence": 0.99 }
  ],
  "usage": { "input_chars": 16, "latency_ms": 24 }
}

WebSocket

GET /ws/translate 会升级为 WebSocket。你发送的每一帧是一个 TranslateRequest；你收到的每一帧要么是 TranslateResponse，要么是 ErrorResponse。当你要连续翻译大量短内容、希望省去每次请求的开销时适合用它。

JavaScript

const socket = new WebSocket(
  "ws://127.0.0.1:49321/v1/ws/translate?token=" + PRIVY_TOKEN
);

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({
    target: "ja",
    texts: ["The quarterly invoice is attached."]
  }));
});

socket.addEventListener("message", (event) => {
  const frame = JSON.parse(event.data);
  if (frame.error) console.error(frame.error.message);
  else console.log(frame.results[0].text);
});

限制与语言

GET /capabilities 返回实时数值；下面这些是默认值。

max_items128

max_chars_per_item8000

max_total_chars50000

语言代码

目标语言使用 BCP 47 代码。source 还额外接受 auto。

enEnglish
zh-Hans简体中文
zh-Hant繁體中文
ja日本語
ko한국어
frFrançais
deDeutsch
esEspañol
viTiếng Việt
thไทย
idBahasa Indonesia
msBahasa Melayu
filFilipino
myမြန်မာ
kmខ្មែរ
loລາວ

错误

失败时返回单个 error 对象，其中带有稳定的 type。

invalid_request_error 400, 413, 422 请求体格式有误、字段未知，或批量超出限制。

authentication_error 401, 403 API 令牌缺失、错误或已吊销。

server_error 500, 503 翻译链路失败，或应用尚未就绪。

400 · application/json

{
  "error": {
    "code": "batch_too_large",
    "message": "texts exceeds max_items (128)",
    "type": "invalid_request_error",
    "param": "texts"
  }
}