PrivatAI
← Startseite

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, frequency_penalty, presence_penalty, stop, seed — Optional. Standard OpenAI-Parameter. max_tokens ist tarifabhängig begrenzt (Essential 8.192, Professional 32.768).

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

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
Testzugang64.096—Standardmodell
Essential308.192~ 20 Mio. TokensStandardmodell (gpt-oss-120b)
Professional6032.768~ 40 Mio. TokensStandardmodell (gpt-oss-120b)
~ 4 Mio. TokensFlaggschiff-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.