API Dokumentation

Vollständige Referenz für die PrivatAI REST API. Einfach, datenschutzfreundlich und leistungsstark.

Einführung

Die PrivatAI API bietet Zugang zu LLM-Modellen (z.B. gpt-oss-120b, GLM-5.2), gehostet in der EU mit voller DSGVO-Konformität. Alle Anfragen werden über HTTPS übertragen und Ihre Prompts werden nicht gespeichert.

🔒 Datenschutz: Wir speichern keine Prompts oder Antworten. Nur Nutzungszähler für die Abrechnung.

Basis-URL

https://privatai.com/api/v1

OpenAI- und Grok-kompatibel: In Ihrem Client nur die Basis-URL auf https://privatai.com/api/v1 setzen (z.B. OPENAI_API_BASE).

Authentifizierung

Authentifizieren Sie sich mit Ihrem API-Schlüssel im Authorization-Header:

http

Authorization: Bearer privat_xxxxxxxxxxxxxxxxxxxx

Ihren API-Schlüssel finden Sie im Dashboard nach der Anmeldung und Zahlung.

Chat Completion

POST /api/v1/chat/completions

Generiert eine Antwort auf Ihre Nachricht. OpenAI-kompatibles Format; standardmäßig eine JSON-Antwort, optional Streaming via Server-Sent Events.

Request Body

Parameter	Typ	Beschreibung
`messages`	array	Erforderlich. Array von Nachrichten (role, content)
`model`	string	Optional. Modell-Key (z.B. gpt-oss-120b). Ohne Angabe: gpt-oss-120b für bezahlte Konten. Alle Modelle: GET /api/v1/models
`stream`	boolean	Optional, Standard false. Bei true: SSE-Stream
`temperature`, `top_p`, `max_tokens`, `presence_penalty`, `stop`, `seed`	—	Optional. Standard OpenAI-Parameter. max_tokens ist tarifabhängig begrenzt (Essential 8.192, Professional 32.768). frequency_penalty und min_p werden akzeptiert, aber nicht angewandt — nutzen Sie presence_penalty.

Einfache Anfrage

bash

curl -X POST https://privatai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-oss-120b", "messages": [{"role": "user", "content": "What is machine learning?"}]}'

Mit Tools (funktionaler Aufruf)

bash

curl -X POST https://privatai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {"role": "user", "content": "What is the weather in Berlin?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          },
          "required": ["location"]
        }
      }
    }
  ],
  "tool_choice": "auto",
  "stream": false
}'

Konversation (Multi-Turn)

bash

curl -X POST https://privatai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {"role": "user", "content": "What is the capital of France?"},
    {"role": "assistant", "content": "The capital of France is Paris."},
    {"role": "user", "content": "What is the population?"}
  ]
}'

Response (SSE Stream, OpenAI-Format)

Die Antwort wird als Server-Sent Events im OpenAI-Format gestreamt:

text/event-stream

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":...,"model":"...","choices":[{"index":0,"delta":{"content":"The"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{"content":" capital"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{"content":" of"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{"content":" France"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{"content":" is"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{"content":" Paris"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":15,"completion_tokens":7,"total_tokens":22}}

Thinking-Modelle (Reasoning)

Modelle wie gpt-oss-120b und GLM-5.2 sind Denk-Modelle. Beim Streamen senden sie optional delta.reasoning (Gedankengang) vor oder vermischt mit delta.content (Antwort).

Behandlung: Accumulieren Sie delta.reasoning für die Begründung (z. B. zum Anzeigen oder Debuggen) und delta.content für die finale Benutzer-Antwort.

json

{"choices":[{"index":0,"delta":{"reasoning":"Let me analyze..."}}]}
{"choices":[{"index":0,"delta":{"content":"The answer is Paris."}}]}

Embeddings

POST /api/v1/embeddings

Wandelt Text in Vektoren um — für RAG (Retrieval-Augmented Generation), semantische Suche, Clustering und Klassifizierung. OpenAI-kompatibel: OpenAI SDK, LangChain und das Vercel AI SDK funktionieren, indem Sie nur die Basis-URL ändern.

🔒 Zustandslos: Wir berechnen die Vektoren und geben sie zurück. PrivatAI speichert weder Ihren Text noch die Vektoren. Ihre Dokumente bleiben bei Ihnen, der Index gehört Ihnen. Inferenz läuft bei Scaleway in Frankreich (EU).

Modelle

Modell	Dimensionen	Eigene dimensions?	Preis (EUR / 1 Mio. Token)
`qwen3-embedding-8b`	4096	Ja — 32…4096	0,10 Eingabe · Ausgabe frei
`bge-multilingual-gemma2`	3584	Nein	0,10 Eingabe · Ausgabe frei

Beide Modelle sind mehrsprachig und können Deutsch und Englisch. Verfügbar in Essential und Professional — kein Premium-Tarif nötig. Standard ist qwen3-embedding-8b: Es ist Matryoshka-trainiert, der Vektor lässt sich also über dimensions verkürzen, ohne die Qualität zu ruinieren. Das ist praktisch entscheidend, denn der HNSW-Index von pgvector lehnt mehr als 2000 Dimensionen ab — mit dimensions: 1024 passt es. bge-multilingual-gemma2 lässt sich nicht kürzen und antwortet auf dimensions mit einem 400, statt Ihre Vektoren still zu verschlechtern.

⚠️ Mischen Sie niemals Modelle oder Dimensionen in einem Index. Vektoren verschiedener Modelle — oder desselben Modells mit unterschiedlichen dimensions — sind nicht vergleichbar. Eine Änderung bedeutet: alles neu einbetten.

Request Body

Parameter	Typ	Beschreibung
`input`	string \| array	Erforderlich. Ein String oder ein Array von Strings (Batch). Vorab tokenisierte Integer-Arrays werden nicht unterstützt.
`model`	string	Optional. Standard: qwen3-embedding-8b.
`dimensions`	integer	Optional. Verkürzt den Vektor. Nur qwen3-embedding-8b (32…4096).
`encoding_format`	string	Optional. Nur float (Standard).

Limits: maximal 2.048 Strings und 1 MB Text pro Anfrage. Die Vektoren kommen in derselben Reihenfolge zurück wie die Eingaben.

bash

curl -X POST https://privatai.com/api/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen3-embedding-8b",
  "input": ["Die Kündigungsfrist beträgt drei Monate.", "Notice period is three months."],
  "dimensions": 1024
}'

Response

json

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, ...] },
    { "object": "embedding", "index": 1, "embedding": [0.0211, -0.0388, ...] }
  ],
  "model": "qwen3-embedding-8b",
  "usage": { "prompt_tokens": 24, "total_tokens": 24 }
}

Embeddings haben keine Ausgabe-Token: completion_tokens ist immer 0 und die Ausgabe ist kostenlos. Abgerechnet werden nur Eingabe-Token.

Mit dem OpenAI SDK

python

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://privatai.com/api/v1",
)

res = client.embeddings.create(
    model="qwen3-embedding-8b",
    input=["Passage eins", "Passage zwei"],
    dimensions=1024,
)

vectors = [row.embedding for row in res.data]

Nutzung abfragen

GET /api/v1/usage

Gibt Ihre aktuelle Nutzung zurück.

bash

curl https://privatai.com/api/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "tokens_used": 15420,
  "prompt_tokens": 5200,
  "completion_tokens": 10220,
  "requests": 89,
  "last_used": "2026-07-02T14:30:00"
}

Modelle auflisten

GET /api/v1/models

Gibt die verfügbaren Modelle zurück (OpenAI-kompatibel). GLM-5.2 erscheint nur bei einem Professional-Abo.

bash

curl https://privatai.com/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Python Beispiel

python

import requests
import json

API_KEY = "YOUR_API_KEY"
URL = "https://privatai.com/api/v1/chat/completions"

def chat(messages):
    response = requests.post(
        URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={"messages": messages},
        stream=True
    )

    for line in response.iter_lines():
        if line.startswith(b"data: "):
            data = json.loads(line[6:])
            if data.get("choices") and data["choices"][0].get("delta", {}).get("content"):
                print(data["choices"][0]["delta"]["content"], end="", flush=True)
            if data.get("choices") and data["choices"][0].get("finish_reason"):
                print()
                return data.get("usage")

chat([{"role": "user", "content": "Explain quantum computing in simple terms."}])

JavaScript Beispiel

javascript

const API_KEY = 'YOUR_API_KEY';

async function chat(messages) {
  const response = await fetch('https://privatai.com/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ messages })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    for (const line of chunk.split('\n')) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        if (data.choices && data.choices[0]?.delta?.content) process.stdout.write(data.choices[0].delta.content);
        if (data.choices && data.choices[0]?.finish_reason) console.log();
      }
    }
  }
}

chat([{ role: 'user', content: 'What is the meaning of life?' }]);

Fehlerbehandlung

Die API gibt Standard-HTTP-Statuscodes zurück:

Code	Bedeutung
`200`	Erfolg
`400`	Ungültige Anfrage (z.B. fehlende messages)
`401`	Ungültiger oder fehlender API-Schlüssel
`402`	Abo inaktiv oder Budget nicht initialisiert — bitte Abo prüfen/erneuern
`403`	Modell erfordert den Professional-Tarif (z.B. GLM-5.2)
`429`	Rate Limit oder monatliches Kontingent überschritten
`500`	Server-Fehler

Rate Limits

Die API begrenzt Anfragen pro Minute je nach Tarif (pro API-Schlüssel). Wird das Limit überschritten, antwortet die API mit HTTP 429. Zusätzlich beinhaltet jeder Tarif ein monatliches Nutzungskontingent; ist es aufgebraucht, antwortet die API bis zum nächsten Abrechnungszyklus ebenfalls mit HTTP 429. Der Web-Chat auf der Website wird separat limitiert.

Tarif	Anfragen / Min	Max. Tokens / Antwort	Volumen / Monat (ca.)	Modelle
Testzugang	6	4.096	—	Standardmodell
Essential	30	8.192	~ 20 Mio. Tokens	Standardmodell (gpt-oss-120b)
Professional	60	32.768	~ 40 Mio. Tokens	Standardmodell (gpt-oss-120b)
Professional	60	32.768	~ 4 Mio. Tokens	Flaggschiff-Modell (GLM-5.2)

⏱️ Anfragen-Limit gilt pro API-Schlüssel — bei HTTP 429 kurz warten und mit Backoff erneut senden. Das monatliche Volumen ist ein Richtwert: Es hängt vom Modell und vom Verhältnis Eingabe/Ausgabe ab; das höherwertige Flaggschiff-Modell verbraucht das Kontingent schneller. Ihre aktuelle Nutzung sehen Sie im Dashboard.

EU-KI-Verordnung: was Sie als Integrator wissen müssen

Die Verordnung (EU) 2024/1689 gilt seit dem 2. August 2026 für Transparenzpflichten. PrivatAI ist Anbieter eines KI-Systems mit allgemeinem Verwendungszweck. Bauen Sie darauf eine Anwendung, sind Sie in der Regel Betreiber — und Anbieter, sobald Sie das Ergebnis unter eigenem Namen in Verkehr bringen. Diese Pflichten treffen dann Sie, nicht uns:

Pflicht	Wann sie greift
Art. 50 Abs. 1 — Offenlegung gegenüber Nutzern	Ihre Anwendung interagiert mit natürlichen Personen. Sie müssen sie darüber informieren, dass sie mit einem KI-System sprechen — es sei denn, das ist aus dem Kontext offensichtlich.
Art. 50 Abs. 4 — Kennzeichnung veröffentlichter Texte	Sie veröffentlichen KI-erzeugten Text, um die Öffentlichkeit über Angelegenheiten von öffentlichem Interesse zu informieren. Gilt außerdem für Deepfakes.
Art. 4 — KI-Kompetenz	Immer. Wer in Ihrem Haus mit dem System arbeitet, muss es hinreichend verstehen — Fähigkeiten, Grenzen, Risiken.
Art. 5 / Anhang III — verbotene und Hochrisiko-Anwendungen	Verbotene Praktiken nach Art. 5 sind vertraglich ausgeschlossen. Hochrisiko-Einsatz nach Anhang III nur nach eigener vorheriger Konformitätsbewertung — der Dienst ist dafür nicht bestimmt (AGB § 5 Abs. 1 lit. e).

⚠️ Maschinenlesbare Kennzeichnung (Art. 50 Abs. 2): Die API gibt derzeit keinen Marker aus, der Ausgaben als KI-erzeugt kennzeichnet — weder als Header noch im JSON. Wenn Ihre Pflichten eine solche Kennzeichnung voraussetzen, planen Sie sie auf Ihrer Seite ein und verlassen Sie sich nicht auf die Antwort. Wir haben die Frage bewertet und die Umsetzung bewusst zurückgestellt, bis die Verhaltenskodizes nach Art. 50 Abs. 7 und die harmonisierten Normen vorliegen; die Entscheidung ist datiert dokumentiert. Sobald wir kennzeichnen, geschieht das additiv und bricht keine bestehende Integration.

Vertragliche Grundlage: AGB § 5 Abs. 1 lit. e und der Auftragsverarbeitungsvertrag § 11. Dies ist eine Orientierung, keine Rechtsberatung — welche Rolle Sie im Einzelfall einnehmen, prüfen Sie mit Ihrem Berater.