Ein Übersetzungsendpunkt, der Ihren Rechner nie verlässt.

Überblick

Aktivieren Sie die Local API in den PrivyTranslate-Einstellungen. Der Dienst lauscht dann nur auf der Loopback-Schnittstelle — er ist von einem anderen Rechner aus nicht erreichbar, und keine Anfrage wird irgendwohin weitergeleitet.

OpenAPI-JSON herunterladen ↓

Authentifizierung

Die Einstellungen zeigen ein API-Token an, sobald die Local API aktiviert ist. Alle Endpunkte außer /health und /capabilities verlangen es. Drei Transportwege werden akzeptiert:

• Header X-Privy-Token — die primäre Form für HTTP-Anfragen.
• Authorization: Bearer — wird sowohl von HTTP-Anfragen als auch vom WebSocket-Handshake akzeptiert.
• ?token= oder ?access_token= — Query-Parameter für WebSocket-Clients im Browser, die keine Header setzen können.

Behandeln Sie das Token wie jedes andere Geheimnis: Es gewährt jedem, der es besitzt, Übersetzung auf Ihrem Rechner.

Endpunkte

Übersetzen

POST /translate nimmt einen Stapel von bis zu 128 Zeichenketten und liefert ein Ergebnis pro Element, in derselben Reihenfolge. source ist standardmäßig auto; target ist erforderlich.

Anfrage

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 akzeptiert selection, paragraph, webpage, subtitle, message oder document. format akzeptiert text, html oder markdown. Unter options legt engine ein bestimmtes Backend fest (local-llm, ollama, lm-studio, openai-compatible), und sensitive: true hält die Anfrage aus dem Übersetzungsverlauf heraus.

Antwort

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

Erkennen

POST /detect liefert für jedes Element einen Sprachcode und einen Konfidenzwert zwischen 0 und 1, ohne es zu übersetzen.

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

{
  "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 wechselt auf WebSocket. Jeder Frame, den Sie senden, ist ein TranslateRequest; jeder empfangene Frame ist entweder ein TranslateResponse oder ein ErrorResponse. Nutzen Sie es, wenn Sie einen Strom kurzer Elemente übersetzen und den Aufwand pro Anfrage vermeiden wollen.

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);
});

Grenzen und Sprachen

GET /capabilities meldet die aktuellen Werte; dies sind die Standardwerte.

Sprachcodes

Zielsprachen verwenden BCP-47-Codes. source akzeptiert zusätzlich 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ລາວ

Fehler

Fehlschläge liefern ein einzelnes error-Objekt mit einem stabilen type.

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