桌面版 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"
  }
}