デスクトップ Local API

概要

PrivyTranslate の設定で Local API を有効にします。サービスはループバックインターフェースだけで待ち受けます。他のマシンからは到達できず、リクエストがどこかへ中継されることもありません。

ベース URLhttp://127.0.0.1:49321/v1

API バージョンv1

対応環境macOS

コンテンツタイプapplication/json

OpenAPI JSON をダウンロード ↓

認証

Local API を有効にすると、設定画面に API トークンが表示されます。/health と /capabilities を除くすべてのエンドポイントで必要です。次の 3 つの渡し方に対応しています。

X-Privy-Token ヘッダー — HTTP リクエストでの基本形です。
Authorization: Bearer — HTTP リクエストでも WebSocket のハンドシェイクでも使えます。
?token= または ?access_token= — ヘッダーを設定できないブラウザの WebSocket クライアント向けのクエリパラメータです。

トークンは他の認証情報と同じように扱ってください。持っている相手に、あなたのマシンでの翻訳を許可することになります。

エンドポイント

GET /health サービスの稼働状況と準備状態公開 GET /capabilities エンジン、言語、機能、制限公開 POST /translate 1 件以上のテキストを翻訳トークン 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ລາວ

エラー

失敗時は、安定した type を持つ単一の error オブジェクトが返ります。

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"
  }
}