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-Schlüssel, siehe Authentifizierung. - Scopes:
chat,embeddings,rerank,speech,transcribe,mcp,decisions,extractions. 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, dazu die Festlegungen der Org für SovrGPT Desktop (desktop). |
GET /v1/usage | – | Verbrauch und Ausgabenlimit im laufenden Monat, für die Organisation und den Aussteller des Schlüssels. |
POST /v1/chat/completions | chat | Chat, als JSON oder Stream (SSE). |
POST /v1/embeddings | embeddings | Embeddings, OpenAI-kompatibel (bge-m3 als Standard, nomic-embed-code; bei STACKIT stackit-qwen3-vl-embedding-8b mit wählbarer Länge über dimensions und stackit-e5-mistral-7b, Übersicht). |
POST /v1/rerank | rerank | Reranking, Cohere-kompatibel (bge-reranker-base). |
POST /v1/audio/speech | speech | Sprachausgabe: Stimmenkatalog (voice: "bib-m-40"), derzeit Vorgabe voxtral-mini-tts; weitere Engines über provider (qwen, vorläufig; supertonic; cosyvoice mit Emotion, Inline-Tags und Stimmklon). |
GET /v1/audio/voices | – | Stimmenkatalog mit Hörproben und der Angabe, ob Ihre Organisation wählen darf. |
POST /v1/audio/voices/designs | speech | 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 | – | Sprecherkartei (Klangfarbe, Charakter, Tempo, Satzmelodie, Stimmlage, Einsatzgebiet), Grenzen und ob der Dienst geschaltet ist. |
POST /v1/audio/transcriptions | transcribe | Spracherkennung (Voxtral). |
GET /v1/audio/transcriptions/realtime | transcribe | Echtzeit-Spracherkennung per WebSocket (wss://): Audio in Blöcken rein, Text Wort für Wort zurück. Mistrals Ereignisformat, nicht OpenAIs Realtime-Protokoll. Vorschau. |
POST /v1/audio/uploads | transcribe | Hochlade-Freigabe 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 und die feste Bild-Version sovr-decision-mm-1.0, Vorgabe dieser Organisation, Betreiber, Land, Messwerte. |
POST /v1/extractions | extractions | Extraction Engine: Text und bis zu vier Fotos rein, typisierte Felder (Code, Datum, Betrag, Ja/Nein, Fundort …) mit confidence und p_null raus. |
GET /v1/extractions/models | – | Feste Versionen (sovr-extract-1.0), Abrufbarkeit, Betreiber, Land, Feldtypen, Grenzen. |
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. |
Geplant ist außerdem POST /v1/images/generations (Bildgenerierung mit Z-Image, Qwen-Image,
FLUX.2 als REST). Heute erzeugen Sie Bilder 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 des Schlüssels (key_spend_limit), der Person, die ihn angelegt hat (user_spend_limit), oder der Organisation (org_spend_limit) ist erreicht. | Limit des Schlüssels unter Einstellungen → API-Keys, die übrigen unter Einstellungen → Ausgabenlimits prüfen. |
402 quota_exceeded | Im Tarif Free hat die Person, die den Schlüssel angelegt hat, ihr kostenloses Kontingent von 5 € im Monat aufgebraucht (tier_spend_limit), gezählt über alle ihre kostenlosen Organisationen zusammen. Ein höheres Ausgabenlimit hebt es nicht an. Lautet die Meldung „lässt sich gerade nicht prüfen“, ist nichts aufgebraucht: der Stand war nur kurz nicht lesbar. | Ab dem 1. des Folgemonats wieder verfügbar, oder unter Einstellungen → Verbrauch ein Upgrade anfragen. Bei „nicht prüfen“ nach einigen Sekunden wiederholen. |
429 | Der Modellanbieter drosselt. | Mit Backoff wiederholen. |
503 model_cold_start | Ein selbst betriebenes Modell fährt hoch. | Nach Retry-After (60 s) wiederholen. |
Verbrauch abfragen: GET /v1/usage
Zeigt, wie viel im laufenden Kalendermonat (UTC) verbraucht ist und wo die Grenze liegt —
dieselben Zahlen, an denen eine Anfrage mit 402 scheitert. Kein Scope nötig.
{
"object": "usage",
"currency": "EUR",
"period": { "start": "2026-11-01T00:00:00.000Z", "end": "2026-12-01T00:00:00.000Z" },
"complete": true,
"tier": "free",
"org": { "spent_micro_eur": 640000, "limit_micro_eur": null },
"user": {
"spent_micro_eur": 1500000,
"limit_micro_eur": 5000000,
"member_spent_micro_eur": 640000,
"member_limit_micro_eur": null
},
"key": { "spent_micro_eur": 420000, "limit_micro_eur": null },
"effective": { "limit_micro_eur": 5000000, "remaining_micro_eur": 3500000, "level": "tier" }
}- Alle Beträge in Mikro-Euro (1 € = 1.000.000).
limit_micro_eur: nullheißt kein Limit. period.endist der Beginn des nächsten Monats; dann beginnt die Zählung neu.tierist der Tarif der Organisation.org: Verbrauch der ganzen Organisation und ihr Ausgabenlimit.user: die Person, die den Schlüssel angelegt hat (null, wenn es sie nicht mehr gibt).spent_micro_eurzählt immer gegenlimit_micro_eur. In bezahlten Tarifen sind das ihr Verbrauch und ihr eigenes Limit in dieser Organisation. Im Tarif Free istlimit_micro_eurdas Kontingent von 5 € undspent_micro_eurihr Verbrauch über alle ihre kostenlosen Organisationen zusammen; ihr eigenes Limit in dieser Organisation steht getrennt inmember_limit_micro_eur, gezählt gegenmember_spent_micro_eur(diemember_*-Felder gibt es nur im Tarif Free). Ohne Person steht das Kontingent beiorg, weil es dann gegen die ganze Organisation zählt.key: der API-Schlüssel dieser Anfrage — sein Verbrauch im Monat und sein eigenes Limit (Einstellungen → API-Keys,null= keines). Es gilt zusätzlich und hebt keine andere Grenze an.effective: die engste Grenze für die nächste Anfrage.levelisttier(kostenloses Kontingent),key(Limit des Schlüssels),user(eigenes Limit in dieser Organisation),orgodernull(keine Grenze).complete: falseheißt: nicht alle Vorgänge konnten gelesen werden. Die Beträge sind dann eine Untergrenze,remaining_micro_eureine Obergrenze.- Die Antwort darf bis zu 30 Sekunden alt sein (
Cache-Control: private, max-age=30). Ist der Verbrauch gerade nicht lesbar, kommt503mitRetry-After: 30statt einer Null.
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, auch in Echtzeit.
- Decision Engine: Entscheidungen statt Antworttexte.
- Extraction Engine: typisierte Felder aus Text und Fotos lesen.
- 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.