API
OpenAI-compatible API
The SovrGPT API speaks the OpenAI schema: base URL, sov_… bearer keys, scopes and every endpoint for chat, embeddings, audio and decisions.
The SovrGPT API is OpenAI-compatible. Existing OpenAI clients work once you change the base URL, the API key and the model ID. Catalogue models run in EU data centres.
- Base URL:
https://sovrgpt.com/api/v1 - Header:
Authorization: Bearer sov_… - Key:
sov_followed by 48 hex characters, created under Settings → API keys; see Authentication. - Scopes:
chat,embeddings,rerank,speech,transcribe,mcp,decisions. A new key has all of them by default; narrow them down per use case.
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": "Hello!"}]}'Endpoints
| Endpoint | Scope | Purpose |
|---|---|---|
GET /v1/models | – | Every model you can use: chat, embeddings, re-ranking, speech, decisions. |
GET /v1/me | – | What this key may do: every scope with a granted flag. |
POST /v1/chat/completions | chat | Chat, as JSON or as a stream (SSE). |
POST /v1/embeddings | embeddings | Embeddings, OpenAI-compatible (bge-m3 as the default, nomic-embed-code; at STACKIT stackit-qwen3-vl-embedding-8b with a selectable length via dimensions and stackit-e5-mistral-7b, overview). |
POST /v1/rerank | rerank | Re-ranking, Cohere-compatible (bge-reranker-base). |
POST /v1/audio/speech | speech | Text-to-speech: voice catalogue (voice: "bib-m-40"), currently defaults to voxtral-mini-tts; further engines via provider (qwen, preliminary; supertonic; cosyvoice with emotion, inline tags and voice cloning). |
GET /v1/audio/voices | – | The voice catalogue with samples and whether your organisation may select. |
POST /v1/audio/voices/designs | speech | Design your own fictional voice from a description; auto_adopt: true does it in one go. Plus GET (list), /{id}, /{id}/adopt, /suggest. |
GET /v1/audio/voices/design-options | – | The casting sheet (timbre, character, pace, intonation, register, use case), the limits and whether the service is switched on. |
POST /v1/audio/transcriptions | transcribe | Speech-to-text (Voxtral). |
POST /v1/audio/uploads | transcribe | Upload ticket for recordings above 4.5 MiB: a signed address you upload to directly, limit 100 MiB. |
POST /v1/decisions | decisions | Decision Engine: state and questions with fixed options in, probabilities out. No prose, one forward pass per question. |
GET /v1/decisions/presets | – | Server-side question packs (ticket-routing-v1). |
GET /v1/decisions/models | – | sovr-decision-v1/-v2, this organisation's default, operator, country, measurements. |
POST /mcp/mcp | mcp | MCP server with chat, search, image and video tools for Cursor, Claude Desktop, Zed, Windsurf. |
POST /mcp/docs/mcp | no key | Public documentation search via MCP. |
POST /v1/images/generations | – | Planned: image generation (Z-Image, Qwen-Image, FLUX.2) as REST. Available today in chat and via MCP. |
Endpoints without a scope still need a valid key, except the documentation search. The machine-readable description is the OpenAPI specification.
Compatibility with the OpenAI schema
We follow the OpenAI v1 schema as of 2026-04. Extra fields such as tier in the model list
extend the schema; standard clients ignore them. Other OpenAI fields (e.g. seed,
logit_bias) are passed through to the model server. Whether they take effect depends on the
model.
Limits
The API currently enforces no fixed request limit per key. Your client should still handle these responses:
| Status | Meaning | What to do |
|---|---|---|
402 quota_exceeded | The spend limit of the organisation (org_spend_limit) or of the person who created the key (user_spend_limit) has been reached. | Check the limit under Settings → Spend limits. |
429 | The model provider is throttling. | Retry with backoff. |
503 model_cold_start | A self-hosted model is starting up. | Retry after Retry-After (60 s). |
Versioning
- Current version:
v1. - Breaking changes get a new version number (
v2,v3, …) with at least six months of overlap. - New fields and new model IDs arrive without a new version.
GET /v1/modelstells you which models exist right now.
Next
- Authentication: keys, scopes, error codes.
- GET /v1/models: query the available models.
- POST /v1/chat/completions: the main endpoint.
- Audio: speech synthesis and transcription.
- Decision Engine: decisions instead of prose.
- MCP server: wire SovrGPT into Cursor, Claude Desktop, Zed or Windsurf.
- SDK examples: Python, Node.js, .NET, Java, Go.
- Switching from OpenAI: the move step by step.
- OpenAPI specification: for Swagger UI, Redoc, Postman.