Lathra.ai API Dokumentation

Version: 2.0.0
Letzte Aktualisierung: 15. Februar 2026

Überblick

Lathra.ai ist ein DSGVO-konformer Proxy für US-amerikanische Large Language Models (LLMs). Die API tokenisiert personenbezogene Daten (PII) automatisch und kontexterhaltend, bevor sie an OpenAI, Anthropic oder andere LLM-Anbieter gesendet werden. Ihre personenbezogenen Daten bleiben in der EU, während Sie die volle Leistungsfähigkeit moderner LLMs nutzen können.

Kernfunktionen

Lathra.ai bietet eine OpenAI-kompatible API mit automatischer PII-Pseudonymisierung. Die Tokenisierung erfolgt durch ein intent-basiertes LLM-System, das semantische Kontexte versteht und nur relevante Informationen schützt. Nicht-personenbezogene Texte werden automatisch erkannt und ohne Tokenisierung weitergeleitet (Bypass), um Kosten zu sparen. Die Detokenisierung kann optional übersprungen werden, was besonders für HR-SaaS- oder Medical-SaaS-Anwendungen relevant ist, bei denen Daten vor End-Nutzern geschützt werden müssen.

Authentifizierung

Lathra.ai verwendet einen Dual-Key-Ansatz: Sie benötigen sowohl einen Lathra API Key als auch Ihren eigenen LLM-Provider API Key. Der Lathra Key authentifiziert Ihre Anfragen, während der Provider Key direkt an den Upstream-LLM weitergeleitet wird. Lathra speichert Ihre LLM API Keys niemals.

Erforderliche Header:

| Header | Beschreibung | Beispiel | |--------|--------------|----------| | X-Lathra-API-Key | Ihr Lathra API Key (erforderlich) | lathra_live_abc123... | | X-Upstream-Provider | LLM-Anbieter (erforderlich) | openai | | X-Upstream-Key | Ihr LLM API Key (erforderlich) | sk-proj-... |

Endpoints

POST /v1/chat/completions

Der Hauptendpoint für DSGVO-konforme Chat-Completions. Kompatibel mit der OpenAI Chat Completions API.

Base URL: https://api.lathra.ai (Produktion) | http://localhost:8001 (Entwicklung)

Request Headers

| Header | Typ | Beschreibung | |--------|-----|--------------| | X-Lathra-API-Key | string (required) | Ihr Lathra API Key | | X-Upstream-Provider | enum (required) | openai | anthropic | together | groq | | X-Upstream-Key | string (required) | Ihr LLM Provider API Key | | X-User-Id | string (optional) | User-Identifier für Audit-Logs | | X-Request-ID | string (optional) | Request-Tracking-ID | | X-Prompt-Version | enum (optional) | legacy | split_v1 (default: legacy) | | X-Skip-Detokenization | string (optional) | true | 1 um Detokenisierung zu überspringen |

Request Body

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "Herr Schmidt arbeitet bei der BMW AG in München."
    }
  ],
  "temperature": 0.7,
  "max_tokens": null,
  "stream": false,
  "token_mappings": {}
}

Parameter:

| Parameter | Typ | Beschreibung | |-----------|-----|--------------| | model | string | LLM-Modell (z.B. gpt-4o-mini, claude-3-5-sonnet-20241022) | | messages | array | Array von Message-Objekten mit role und content | | temperature | float | Sampling-Temperatur (0.0 - 2.0, default: 0.7) | | max_tokens | integer | Maximale Anzahl Tokens in der Antwort | | stream | boolean | Streaming-Modus aktivieren (default: false) | | token_mappings | object | Token-Mappings aus vorherigen Requests (für Konversationen) |

Response

{
  "id": "chatcmpl-550e8400-e29b-41d4-a716-446655440000",
  "object": "chat.completion",
  "created": 1739544000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Herr Schmidt arbeitet bei der BMW AG in München."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 12,
    "total_tokens": 57
  },
  "lathra_metadata": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "provider": "openai",
    "tokenization_applied": true,
    "detokenization_skipped": false,
    "processing_time_ms": 1234,
    "llm_duration_ms": 567,
    "tokenized_input": "[[ACTOR_PERSON_1]] arbeitet bei der [[ORGANIZATION_TYPE_COMPANY_1]] in [[CONTEXT_CLASS_LOCATION_CITY_1]].",
    "tokenized_response": "[[ACTOR_PERSON_1]] arbeitet bei der [[ORGANIZATION_TYPE_COMPANY_1]] in [[CONTEXT_CLASS_LOCATION_CITY_1]].",
    "mappings": [
      {
        "token": "[[ACTOR_PERSON_1]]",
        "text": "Herr Schmidt"
      },
      {
        "token": "[[ORGANIZATION_TYPE_COMPANY_1]]",
        "text": "BMW AG"
      },
      {
        "token": "[[CONTEXT_CLASS_LOCATION_CITY_1]]",
        "text": "München"
      }
    ],
    "rare_disease_handling": null,
    "prompt_version": "split_v1",
    "prompt_hash": "a1b2c3d4..."
  }
}

Response-Felder:

| Feld | Beschreibung | |------|--------------| | lathra_metadata.tokenization_applied | true wenn PII tokenisiert wurde, false bei Bypass | | lathra_metadata.detokenization_skipped | true wenn Detokenisierung übersprungen wurde | | lathra_metadata.tokenized_input | Tokenisierter Input-Text (für Debugging) | | lathra_metadata.tokenized_response | Tokenisierte LLM-Antwort (vor Detokenisierung) | | lathra_metadata.mappings | Array von Token-zu-Text-Mappings | | lathra_metadata.prompt_version | Verwendete Prompt-Version |

GET /health

Health-Check-Endpoint für Monitoring und Load Balancing.

Response

{
  "status": "healthy",
  "service": "lathra-proxy",
  "version": "2.0.0"
}

GET /

Root-Endpoint mit API-Informationen.

Response

{
  "service": "Lathra.ai DSGVO-Compliant AI Proxy",
  "version": "2.0.0",
  "endpoints": [
    "POST /v1/chat/completions",
    "GET /health"
  ]
}

Unterstützte LLM-Provider

OpenAI

Provider-ID: openai

Unterstützte Modelle:

gpt-4o - Neuestes Flagship-Modell
gpt-4o-mini - Schnelles, kostengünstiges Modell
gpt-4-turbo - Vorheriges Flagship-Modell
gpt-3.5-turbo - Legacy-Modell

API Key Format: sk-proj-... oder sk-...

Anthropic

Provider-ID: anthropic

Unterstützte Modelle:

claude-3-5-sonnet-20241022 - Neuestes Sonnet-Modell
claude-3-opus-20240229 - Leistungsstärkstes Modell

API Key Format: sk-ant-...

Together AI

Provider-ID: together

Unterstützte Modelle:

meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo - Open-Source Llama 3.1

API Key Format: Beliebiges Format

Groq

Provider-ID: groq

Unterstützte Modelle:

llama-3.3-70b-versatile - Schnelles Llama 3.3
mixtral-8x7b-32768 - Mixtral MoE-Modell

API Key Format: gsk_...

Prompt-Versionen

Lathra.ai bietet zwei Prompt-Versionen für die Tokenisierung:

Legacy (Standard)

Die Legacy-Version verwendet einen monolithischen Prompt mit ca. 6000 Tokens. Diese Version ist bewährt und stabil, verursacht jedoch höhere Tokenisierungs-Kosten.

Verwendung: Setzen Sie X-Prompt-Version: legacy oder lassen Sie den Header weg.

Split v1 (Empfohlen)

Die Split v1-Version verwendet 10 modulare Prompt-Dateien mit ca. 1300 Tokens (77,8% Reduktion). Diese Version ist optimiert für Token-Effizienz und reduziert Tokenisierungs-Kosten um ca. 80%.

Verwendung: Setzen Sie X-Prompt-Version: split_v1.

Vorteile:

77,8% Token-Reduktion gegenüber Legacy
Modulare Architektur (10 Prompt-Dateien)
Zentralisierte Verbote in M4_CORE
Keine Duplikate mehr

Tokenisierung

Was wird tokenisiert?

Lathra.ai tokenisiert automatisch folgende Kategorien personenbezogener Daten:

| Kategorie | Beispiele | Token-Format | |-----------|-----------|--------------| | Personen | Namen, Anreden | [[ACTOR_PERSON_1]] | | Organisationen | Firmen, Behörden | [[ORGANIZATION_TYPE_COMPANY_1]] | | Kontaktdaten | E-Mails, Telefonnummern | [[CONTEXT_CLASS_CONTACT_EMAIL_1]] | | Adressen | Straßen, PLZ, Städte | [[CONTEXT_CLASS_LOCATION_CITY_1]] | | Zeitangaben | Geburtsdaten, Termine | [[CONTEXT_CLASS_TIME_DATE_BIRTH_1]] | | Seltene Systeme | Proprietäre Software (<1000 Nutzer) | [[SYSTEM_CLASS_CUSTOM_1]] |

Was wird NICHT tokenisiert?

Um Kosten zu sparen und Kontext zu erhalten, werden folgende Informationen nicht tokenisiert:

Sprachen (Deutsch, Englisch, Französisch, etc.)
Häufige Software (SAP, MS Office, Excel, etc.)
Hobbies und Interessen (Fußball, Lesen, etc.)
Allgemeinwissen (Hauptstädte, historische Fakten, etc.)

Bypass-Logik

Wenn Lathra.ai erkennt, dass ein Text keine personenbezogenen Daten enthält, wird die Tokenisierung automatisch übersprungen (Bypass). Dies spart Tokenisierungs-Kosten und reduziert Latenz.

Beispiel:

// Request
{
  "messages": [{"role": "user", "content": "Was ist die Hauptstadt von Frankreich?"}]
}

// Response
{
  "lathra_metadata": {
    "tokenization_applied": false,
    "metadata": {
      "bypassed": true,
      "gdpr_relevant": false
    }
  }
}

Skip Detokenization

Für bestimmte Anwendungsfälle (z.B. HR-SaaS, Medical-SaaS) ist es sinnvoll, die Detokenisierung zu überspringen, damit End-Nutzer nur Tokens sehen und nicht die Original-Daten.

Verwendung

Setzen Sie den Header X-Skip-Detokenization: true oder X-Skip-Detokenization: 1.

Beispiel

curl -X POST https://api.lathra.ai/v1/chat/completions \
  -H "X-Lathra-API-Key: lathra_live_abc123" \
  -H "X-Upstream-Provider: openai" \
  -H "X-Upstream-Key: sk-proj-xyz" \
  -H "X-Skip-Detokenization: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Herr Schmidt arbeitet bei BMW."}]
  }'

Response:

{
  "choices": [{
    "message": {
      "content": "[[ACTOR_PERSON_1]] arbeitet bei [[ORGANIZATION_TYPE_COMPANY_1]]."
    }
  }],
  "lathra_metadata": {
    "detokenization_skipped": true
  }
}

Use Cases

HR-SaaS: Bewerberdaten tokenisiert an HR-Software senden, ohne dass HR-Mitarbeiter echte Namen/Adressen sehen.

Medical-SaaS: Patientendaten tokenisiert an Analyse-Tools senden, ohne dass Dritte Zugriff auf PII haben.

Legal-SaaS: Mandantendaten tokenisiert an Dokumenten-Management-Systeme senden.

Streaming

Lathra.ai unterstützt Server-Sent Events (SSE) für Streaming-Responses.

Verwendung

Setzen Sie "stream": true im Request Body.

Beispiel

curl -X POST https://api.lathra.ai/v1/chat/completions \
  -H "X-Lathra-API-Key: lathra_live_abc123" \
  -H "X-Upstream-Provider: openai" \
  -H "X-Upstream-Key: sk-proj-xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Erkläre Quantenphysik."}],
    "stream": true
  }'

Response (SSE):

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"Quantenphysik"}}]}

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":" ist"}}]}

data: [DONE]

Fehlerbehandlung

Lathra.ai gibt strukturierte Fehler im JSON-Format zurück.

Fehler-Codes

| HTTP Status | Beschreibung | |-------------|--------------| | 400 | Ungültige Request-Parameter | | 401 | Authentifizierung fehlgeschlagen | | 403 | Zugriff verweigert | | 429 | Rate Limit überschritten | | 500 | Interner Server-Fehler | | 502 | Upstream-LLM-Fehler | | 503 | Service temporär nicht verfügbar |

Fehler-Response

{
  "error": {
    "message": "Tokenization failed: LLM timeout",
    "type": "tokenization_error",
    "code": "llm_timeout"
  }
}

Code-Beispiele

Python

import requests

response = requests.post(
    "https://api.lathra.ai/v1/chat/completions",
    headers={
        "X-Lathra-API-Key": "lathra_live_abc123",
        "X-Upstream-Provider": "openai",
        "X-Upstream-Key": "sk-proj-xyz",
        "X-Prompt-Version": "split_v1",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-4o-mini",
        "messages": [
            {"role": "user", "content": "Herr Schmidt arbeitet bei BMW."}
        ]
    }
)

data = response.json()
print(data["choices"][0]["message"]["content"])
print(f"Tokenization applied: {data['lathra_metadata']['tokenization_applied']}")

Node.js

const response = await fetch("https://api.lathra.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    "X-Lathra-API-Key": "lathra_live_abc123",
    "X-Upstream-Provider": "openai",
    "X-Upstream-Key": "sk-proj-xyz",
    "X-Prompt-Version": "split_v1",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    messages: [
      { role: "user", content: "Herr Schmidt arbeitet bei BMW." }
    ]
  })
});

const data = await response.json();
console.log(data.choices[0].message.content);
console.log(`Tokenization applied: ${data.lathra_metadata.tokenization_applied}`);

cURL

curl -X POST https://api.lathra.ai/v1/chat/completions \
  -H "X-Lathra-API-Key: lathra_live_abc123" \
  -H "X-Upstream-Provider: openai" \
  -H "X-Upstream-Key: sk-proj-xyz" \
  -H "X-Prompt-Version: split_v1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Herr Schmidt arbeitet bei BMW."}
    ]
  }'

Preise

Die Nutzung von Lathra.ai kostet 0,01€ pro 1.000 Tokens (Tokenisierung + Detokenisierung). Die Kosten für den Upstream-LLM (OpenAI, Anthropic, etc.) kommen hinzu und werden direkt von Ihrem LLM-Provider abgerechnet.

Beispielrechnung:

Input: 100 Tokens → 0,001€ Lathra-Kosten
Output: 50 Tokens → 0,0005€ Lathra-Kosten
Gesamt Lathra: 0,0015€
Plus OpenAI-Kosten (z.B. 0,002€ für gpt-4o-mini)
Total: 0,0035€

Best Practices

1. Verwenden Sie split_v1

Die Split v1-Prompt-Version reduziert Tokenisierungs-Kosten um 80%. Setzen Sie X-Prompt-Version: split_v1 für alle Requests.

2. Nutzen Sie Bypass

Lathra.ai erkennt automatisch nicht-personenbezogene Texte und überspringt die Tokenisierung. Dies spart Kosten und Latenz.

3. Skip Detokenization für SaaS

Wenn Sie Daten vor End-Nutzern schützen müssen (z.B. HR-SaaS), verwenden Sie X-Skip-Detokenization: true.

4. Monitoring

Überwachen Sie lathra_metadata.tokenization_applied und lathra_metadata.processing_time_ms, um die Performance zu tracken.

5. Error Handling

Implementieren Sie Retry-Logik für 502 (Upstream-Fehler) und 503 (Service nicht verfügbar).

Support

Bei Fragen oder Problemen wenden Sie sich an:

E-Mail: [email protected]
Dokumentation: https://lathra.ai/docs
Status: https://status.lathra.ai

Lathra.ai API Dokumentation

Überblick

Kernfunktionen

Authentifizierung

Endpoints

POST /v1/chat/completions

Request Headers

Request Body

Response

GET /health

Response

GET /

Response

Unterstützte LLM-Provider

OpenAI

Anthropic

Together AI

Groq

Prompt-Versionen

Legacy (Standard)

Split v1 (Empfohlen)

Tokenisierung

Was wird tokenisiert?

Was wird NICHT tokenisiert?

Bypass-Logik

Skip Detokenization

Verwendung

Beispiel

Use Cases

Streaming

Verwendung

Beispiel

Fehlerbehandlung

Fehler-Codes

Fehler-Response

Code-Beispiele

Python

Node.js

cURL

Preise

Best Practices

1. Verwenden Sie split_v1

2. Nutzen Sie Bypass

3. Skip Detokenization für SaaS

4. Monitoring

5. Error Handling

Support

🍪 Cookie-Einstellungen