API: Chat Completions

OpenAI-kompatibler Chat-Completions-Endpunkt von Kasimir mit Bearer-API-Key, Streaming, Modell-Governance und Usage-Abrechnung.

Unter https://kasimir.ai/api/v1 stellt Kasimir eine OpenAI-kompatible Schnittstelle bereit. POST /api/v1/chat/completions nimmt denselben Request-Body wie die OpenAI Chat Completions API entgegen. Es gelten die Regeln eurer Firma: Firmen-API-Schlüssel, nur freigegebene Modelle, EU-Freigabe und Monatsbudget. Bestehende OpenAI-SDKs funktionieren ohne Code-Änderung – es genügt, base_url und api_key zu setzen.

Endpunkt

Authentifizierung

Alle Aufrufe werden über einen Firmen-API-Key authentifiziert, der im Header Authorization: Bearer <secret> mitgesendet wird. Keys haben das Format kasi_<32-Zeichen> und werden in der Kasimir-Oberfläche unter Administration → Zugriff von Workspace-Ownern oder -Admins erzeugt.

Jeder Key trägt Scopes. Neu erstellte Keys erhalten standardmäßig chat:read und chat:write. Für Chat Completions ist chat:write erforderlich — fehlt der Scope, antwortet die API mit 403.

# Schlägt mit 401 fehl, wenn der Header fehlt oder der Key ungültig/widerrufen ist.
Authorization: Bearer kasi_abcdef0123456789abcdef0123456789

Request-Body

Der Body folgt dem OpenAI-Schema. model und messages sind Pflicht. Weitergereicht werden nur diese Felder der OpenAI-Chat-API: temperature, top_p, max_tokens, max_completion_tokens, stop, n, presence_penalty, frequency_penalty, seed, response_format, tools, tool_choice, parallel_tool_calls, user, logit_bias, logprobs, top_logprobs und reasoning_effort. Andere Felder ignoriert die API ohne Fehlermeldung.

Modelle

model erwartet einen Kasimir-Slug, nicht den Modellnamen des Anbieters. Es gelten dieselben Regeln wie bei der Modellauswahl in der App:

• Das Modell muss für deine Firma aktiv und vom Typ chat sein.

• Für eure Firma deaktivierte Modelle sind nicht aufrufbar → 403.

• Nicht-EU-Modelle sind nur verfügbar, wenn eure Firma sie freigeschaltet hat → sonst 403.

• Im Tarif Basic sind nur die selbst gehosteten Modelle aufrufbar; alle anderen ergeben 403.

Die für deinen Schlüssel gültigen Slugs listet GET /api/v1/models auf (siehe unten). Die Antwort nennt im model-Feld immer den Kasimir-Slug.

Antwort (synchron)

Bei stream: false (oder ausgelassenem stream) ist die Antwort ein vollständiges OpenAI-Chat-Completion-Objekt. Das model-Feld wird auf den Kasimir-Slug normalisiert.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "gemma-4-31b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hallo! Wie kann ich helfen?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 18, "completion_tokens": 9, "total_tokens": 27 }
}

Antwort (Streaming)

Bei stream: true antwortet der Endpunkt mit Content-Type: text/event-stream im OpenAI-Format (data: {…}-Zeilen, abschließend data: [DONE]).

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"gemma-4-31b","choices":[{"index":0,"delta":{"role":"assistant","content":"Hallo"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","model":"gemma-4-31b","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":18,"completion_tokens":9,"total_tokens":27}}

data: [DONE]

Budget & Usage-Metering

Jeder Aufruf wird vor der Weiterleitung gegen das Monats-Budget der Firma geprüft. Ist ein Monatsbudget gesetzt und hat der gesamte KI-Verbrauch eurer Firma im laufenden Kalendermonat (API, Chat, Workflows und alles Weitere) es erreicht, antwortet die API mit 402. Ohne Budget gibt es keine Grenze.

Jeder Aufruf wird mit Modell, Tokens und Kosten in Euro verbucht und zählt zum Monatsbudget. Beim Streaming geschieht das am Ende des Streams – auch bei vorzeitigem Abbruch für die bis dahin erzeugten Tokens.

Fehler

Fehler werden im OpenAI-Fehlerschema zurückgegeben, damit Standard-SDKs sie normal verarbeiten:

{ "error": { "message": "Missing scope: chat:write", "type": "permission_error", "code": null } }

Beispiele

curl — synchron

curl https://kasimir.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $KASIMIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4-31b",
    "messages": [
      { "role": "system", "content": "Du bist ein hilfreicher Assistent." },
      { "role": "user", "content": "Schreibe einen Einzeiler über Datenschutz." }
    ],
    "temperature": 0.7
  }'

curl — Streaming

curl -N https://kasimir.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $KASIMIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-4-31b",
    "messages": [{ "role": "user", "content": "Zähle von 1 bis 5." }],
    "stream": true
  }'

Python — OpenAI SDK (synchron)

Da Kasimir OpenAI-kompatibel ist, genügt es, base_url und api_key zu setzen.

from openai import OpenAI

client = OpenAI(
    base_url="https://kasimir.ai/api/v1",
    api_key="kasi_…",  # dein Kasimir-API-Key
)

resp = client.chat.completions.create(
    model="gemma-4-31b",
    messages=[
        {"role": "system", "content": "Du bist ein hilfreicher Assistent."},
        {"role": "user", "content": "Nenne drei Vorteile von EU-Hosting."},
    ],
    temperature=0.7,
)

print(resp.choices[0].message.content)
print(resp.usage)  # prompt_tokens / completion_tokens / total_tokens

Python — OpenAI SDK (Streaming)

from openai import OpenAI

client = OpenAI(base_url="https://kasimir.ai/api/v1", api_key="kasi_…")

stream = client.chat.completions.create(
    model="gemma-4-31b",
    messages=[{"role": "user", "content": "Erkläre RAG in zwei Sätzen."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="", flush=True)
print()

Fehlerbehandlung (Python)

from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://kasimir.ai/api/v1", api_key="kasi_…")

try:
    client.chat.completions.create(
        model="gemma-4-31b",
        messages=[{"role": "user", "content": "Hi"}],
    )
except APIStatusError as e:
    if e.status_code == 402:
        print("Monats-Budget erreicht — bitte Budget erhöhen.")
    elif e.status_code in (401, 403):
        print("Auth/Scope-Problem:", e.message)
    else:
        raise

Verwandte Endpunkte

Dieselbe Authentifizierung, Governance und dasselbe Metering gelten für:

curl https://kasimir.ai/api/v1/models \
  -H "Authorization: Bearer $KASIMIR_API_KEY"