OpenAI-kompatible API

SovrGPT-API im OpenAI-Schema: Basis-URL, Bearer-Schlüssel sov_…, Scopes und alle Endpunkte für Chat, Embeddings, Audio und Entscheidungen.

Die SovrGPT-API ist OpenAI-kompatibel. Bestehende OpenAI-Clients funktionieren, wenn Sie Basis-URL, API-Schlüssel und Modell-ID umstellen. Die Katalogmodelle rechnen in EU-Rechenzentren.

Basis-URL: https://sovrgpt.com/api/v1
Header: Authorization: Bearer sov_…
Schlüssel: sov_ plus 48 Hex-Zeichen, erzeugt unter Einstellungen → API-Keys, siehe Authentifizierung.
Scopes: chat, embeddings, rerank, speech, transcribe, mcp, decisions. Ab Werk hat ein Schlüssel alle; Sie können je Anwendungsfall einschränken.

curl https://sovrgpt.com/api/v1/chat/completions \
  -H "Authorization: Bearer $SOVR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma-4-12b", "messages": [{"role": "user", "content": "Hallo!"}]}'

Endpunkte

Endpunkt	Scope	Zweck
`GET /v1/models`	–	Alle nutzbaren Modelle: Chat, Embeddings, Reranking, Sprache, Entscheidungen.
`GET /v1/me`	–	Rechte dieses Schlüssels: jeder Scope mit `granted`-Angabe.
`POST /v1/chat/completions`	`chat`	Chat, als JSON oder Stream (SSE).
`POST /v1/embeddings`	`embeddings`	Embeddings, OpenAI-kompatibel (`bge-m3`, `nomic-embed-code`).
`POST /v1/rerank`	`rerank`	Reranking, Cohere-kompatibel (`bge-reranker-base`).
`POST /v1/audio/speech`	`speech`	Text-to-Speech: Stimmenkatalog (`voice: "bib-m-40"`), Supertonic oder CosyVoice 3 (Emotion, Inline-Tags, Stimmklon).
`GET /v1/audio/voices`	–	Stimmenkatalog mit Hörproben und der Angabe, ob Ihre Organisation wählen darf.
`POST /v1/audio/voices/designs`	`speech`	Neu: eigene fiktive Stimme aus einer Beschreibung entwerfen, mit `auto_adopt: true` in einem Zug. Dazu `GET` (Liste), `/{id}`, `/{id}/adopt`, `/suggest`.
`GET /v1/audio/voices/design-options`	–	Neu: Sprecherkartei (Klangfarbe, Charakter, Tempo, Satzmelodie, Stimmlage, Einsatzgebiet), Grenzen und ob der Dienst geschaltet ist.
`POST /v1/audio/transcriptions`	`transcribe`	Speech-to-Text (Voxtral).
`POST /v1/audio/uploads`	`transcribe`	Upload-Ticket für Aufnahmen über 4,5 MiB: signierte Adresse für den direkten Upload, Grenze 100 MiB.
`POST /v1/decisions`	`decisions`	Decision Engine: Zustand und Fragen mit festen Optionen rein, Wahrscheinlichkeiten raus. Kein Antworttext, ein Vorwärtsdurchlauf je Frage.
`GET /v1/decisions/presets`	–	Hinterlegte Fragenpakete (`ticket-routing-v1`).
`GET /v1/decisions/models`	–	`sovr-decision-v1`/`-v2`, Vorgabe dieser Organisation, Betreiber, Land, Messwerte.
`POST /mcp/mcp`	`mcp`	MCP-Server mit Chat-, Such-, Bild- und Videowerkzeugen für Cursor, Claude Desktop, Zed, Windsurf.
`POST /mcp/docs/mcp`	kein Schlüssel	Öffentliche Doku-Suche über MCP.
`POST /v1/images/generations`	–	Geplant: Bildgenerierung (Z-Image, FLUX.2) als REST. Heute im Chat und über MCP.

Alle Endpunkte ohne Scope brauchen trotzdem einen gültigen Schlüssel, außer der Doku-Suche. Die maschinenlesbare Beschreibung steht in der OpenAPI-Spezifikation.

Kompatibilität mit dem OpenAI-Schema

Wir folgen dem OpenAI-v1-Schema, Stand 2026-04. Zusätzliche Felder wie tier in der Modellliste ergänzen das Schema; Standard-Clients ignorieren sie. Weitere OpenAI-Felder (z. B. seed, logit_bias) reichen wir an den Modellserver weiter. Ob sie wirken, hängt vom Modell ab.

Limits

Die API setzt derzeit kein festes Anfrage-Limit je Schlüssel durch. Diese Antworten sollte Ihr Client trotzdem behandeln:

Status	Bedeutung	Reaktion
`402` `quota_exceeded`	Ausgabenlimit der Organisation (`org_spend_limit`) oder der Person, die den Schlüssel angelegt hat (`user_spend_limit`), ist erreicht.	Limit unter Einstellungen → Ausgabenlimits prüfen.
`429`	Der Modellanbieter drosselt.	Mit Backoff wiederholen.
`503` `model_cold_start`	Ein selbst betriebenes Modell fährt hoch.	Nach `Retry-After` (60 s) wiederholen.

Versionierung

Aktuelle Version: v1.
Brechende Änderungen bekommen eine neue Versionsnummer (v2, v3 …) mit mindestens sechs Monaten Übergangszeit.
Neue Felder und neue Modell-IDs kommen ohne neue Version. Welche Modelle es gerade gibt, liefert GET /v1/models.

Weiter

Authentifizierung: Schlüssel, Scopes, Fehlercodes.
GET /v1/models: verfügbare Modelle abfragen.
POST /v1/chat/completions: der Hauptendpunkt.
Audio: Sprachausgabe und Transkription.
Decision Engine: Entscheidungen statt Antworttexte.
MCP-Server: SovrGPT in Cursor, Claude Desktop, Zed oder Windsurf einbinden.
SDK-Beispiele: Python, Node.js, .NET, Java, Go.
Von OpenAI wechseln: Umstellung Schritt für Schritt.
OpenAPI-Spezifikation: für Swagger UI, Redoc, Postman.