SovrGPT Dokumentation
API

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

EndpunktScopeZweck
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/completionschatChat, als JSON oder Stream (SSE).
POST /v1/embeddingsembeddingsEmbeddings, 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/rerankrerankReranking, Cohere-kompatibel (bge-reranker-base).
POST /v1/audio/speechspeechSprachausgabe: 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/designsspeechEigene 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/transcriptionstranscribeSpracherkennung (Voxtral).
GET /v1/audio/transcriptions/realtimetranscribeEchtzeit-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/uploadstranscribeHochlade-Freigabe für Aufnahmen über 4,5 MiB: signierte Adresse für den direkten Upload, Grenze 100 MiB.
POST /v1/decisionsdecisionsDecision 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/extractionsextractionsExtraction 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/mcpmcpMCP-Server mit Chat-, Such-, Bild- und Videowerkzeugen für Cursor, Claude Desktop, Zed, Windsurf.
POST /mcp/docs/mcpkein 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:

StatusBedeutungReaktion
402 quota_exceededAusgabenlimit 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_exceededIm 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.
429Der Modellanbieter drosselt.Mit Backoff wiederholen.
503 model_cold_startEin 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: null heißt kein Limit.
  • period.end ist der Beginn des nächsten Monats; dann beginnt die Zählung neu.
  • tier ist 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_eur zählt immer gegen limit_micro_eur. In bezahlten Tarifen sind das ihr Verbrauch und ihr eigenes Limit in dieser Organisation. Im Tarif Free ist limit_micro_eur das Kontingent von 5 € und spent_micro_eur ihr Verbrauch über alle ihre kostenlosen Organisationen zusammen; ihr eigenes Limit in dieser Organisation steht getrennt in member_limit_micro_eur, gezählt gegen member_spent_micro_eur (die member_*-Felder gibt es nur im Tarif Free). Ohne Person steht das Kontingent bei org, 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. level ist tier (kostenloses Kontingent), key (Limit des Schlüssels), user (eigenes Limit in dieser Organisation), org oder null (keine Grenze).
  • complete: false heißt: nicht alle Vorgänge konnten gelesen werden. Die Beträge sind dann eine Untergrenze, remaining_micro_eur eine Obergrenze.
  • Die Antwort darf bis zu 30 Sekunden alt sein (Cache-Control: private, max-age=30). Ist der Verbrauch gerade nicht lesbar, kommt 503 mit Retry-After: 30 statt 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

OpenAI-kompatible API