GemeinsamKI API

Schlüssel

API-Schlüssel legen Sie im Hub unter https://hub.gemeinsamki.de/account an (Abschnitt „API-Schlüssel“). Er gehört in den Kopf Authorization: Bearer <Schlüssel> oder x-api-key. Schlüssel von GemeinsamKI Code (VS Code) gelten hier nicht.

Beispiele

curl:

curl https://api.gemeinsamki.de/v1/chat/completions \
  -H "Authorization: Bearer $GEMEINSAMKI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hallo!"}]}'

Python (Paket openai):

from openai import OpenAI

client = OpenAI(base_url="https://api.gemeinsamki.de/v1", api_key="gki_…")
antwort = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hallo!"}],
)
print(antwort.choices[0].message.content)

Modelle und `"model": "auto"`

GET /v1/models listet die Modelle, die gerade auf Geräten des Verbunds geladen und für Ihren Schlüssel freigegeben sind. Mit "model": "auto" (oder ohne Modell) wählt das System ein geeignetes geladenes Modell; bei Bildern ein Bildmodell. Welcher Hub, welches Gerät und welches Modell geantwortet hat, steht in den Antwortköpfen X-GemeinsamKI-Hub, X-GemeinsamKI-Device und X-GemeinsamKI-Model.

Ein bestimmtes Gerät wählen Sie mit modell@gerät (Gerätename oder Geräte-ID ab 6 Zeichen). Für /v1/embeddings gibt es kein auto: Wechselnde Embedding-Modelle machen gespeicherte Vektoren wertlos, das Modell muss angegeben werden.

Endpunkte

Methode	Pfad	Zweck
GET	`/v1/models`, `/v1/models/{id}`	Modelle (mit Eintrag `auto`)
POST	`/v1/chat/completions`	Chat, auch mit `"stream": true`
POST	`/v1/completions`	Textvervollständigung
POST	`/v1/responses`	Responses-API
POST	`/v1/embeddings`	Embeddings (Modell angeben)
GET	`/v1/gemeinsamki/key`	Regeln und Verbrauch des eigenen Schlüssels

Grenzen

Je Schlüssel kann es ein Ratenlimit (Anfragen je Minute, Köpfe x-ratelimit-*), ein Monatskontingent in Tokens (Köpfe X-GemeinsamKI-Quota-*, Kalendermonat Europe/Berlin), ein Ablaufdatum und eine Modell-Freigabe geben. Ihre Regeln zeigt GET /v1/gemeinsamki/key.
Schlüssel mit Kontingent: höchstens 4 Anfragen gleichzeitig. Wird der Rest knapp, begrenzt das Relay die Länge der Antwort.
Ein Anfragekörper darf höchstens 32 MB groß sein. Je Schlüssel und je Adresse nimmt das Relay höchstens 2 Körper zugleich entgegen; weitere warten kurz, sonst kommt 429 mit Retry-After.
Fehler kommen im OpenAI-Format: {"error": {"message", "type", "param", "code", "status"}}. Jede Antwort trägt eine X-Request-ID; bitte bei Rückfragen angeben.

`previous_response_id`

Bei /v1/responses liegt der Zustand einer Unterhaltung auf dem Gerät, das die vorige Antwort gerechnet hat. Wer mit previous_response_id weiterarbeitet, gibt deshalb das Gerät mit an: "model": "modell@gerät" (Gerät aus dem Kopf X-GemeinsamKI-Device-ID der vorigen Antwort).