Quickstart

Five steps

1. Create a project key in the cabinet

   Keys belong to a project of your organisation. The secret is shown once; store it in an environment variable (SOVEREIGN_API_KEY in the examples), never in code.

2. Send a chat completion with curl

   One request, one answer, the usage in the response body.

3. Use the Python client

   Install the openai package and set base_url to the API host. Nothing else in your code changes; the package only speaks the format — it calls our host, not OpenAI's.

4. Stream

   Set stream=True and stream_options={"include_usage": True}; print the deltas as they arrive and read the usage from the final chunk.

5. Read your usage

   GET /v1/usage returns requests and token counts of your project for a period — the same ledger your invoice is built from.

OpenAI-compatible API format. No OpenAI services are involved. The API host in the examples is the platform host; the cabinet shows the host of your dedicated instance.

curl

curl https://sovereignai-api.mediaholding.tech/v1/chat/completions \
  -H "Authorization: Bearer $SOVEREIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mh-sovereign",
    "messages": [
      {"role": "system", "content": "You answer briefly and cite the clause you rely on."},
      {"role": "user", "content": "Summarise the termination clause of the attached contract in two sentences."}
    ]
  }'

Python — the openai client with base_url

The openai package is used only as a client for the OpenAI-compatible request format. With base_url set to our host no request reaches OpenAI.

import os
from openai import OpenAI   # the OpenAI-compatible client format; no OpenAI service is called

client = OpenAI(
    base_url="https://sovereignai-api.mediaholding.tech/v1",
    api_key=os.environ["SOVEREIGN_API_KEY"],
)

response = client.chat.completions.create(
    model="mh-sovereign",
    messages=[
        {"role": "system", "content": "You answer briefly and cite the clause you rely on."},
        {"role": "user", "content": "Summarise the termination clause of the attached contract in two sentences."},
    ],
)
print(response.choices[0].message.content)
print(response.usage)          # prompt_tokens, completion_tokens, total_tokens

Streaming

stream = client.chat.completions.create(
    model="mh-sovereign",
    messages=[{"role": "user", "content": "List three risks of the clause."}],
    stream=True,
    stream_options={"include_usage": True},   # the final chunk carries usage
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

Thinking for numeric tasks

# Money, prices and quantities: switch the model's thinking on for the request.
response = client.chat.completions.create(
    model="mh-sovereign-reason",
    messages=[{"role": "user", "content": "Invoice total 1,240.50 EUR net; VAT 24 %. Gross amount?"}],
    extra_body={"chat_template_kwargs": {"enable_thinking": True}},
    max_tokens=1024,
)

`chat_template_kwargs` is the llama.cpp runtime's switch for the model's thinking mode; the final request field of the public API is fixed in the generated specification.

Choosing a model

mh-sovereign is the default alias and resolves to the 9B model (mh-sovereign-reason). Use mh-sovereign-small for classification and extraction at speed, mh-sovereign-lingua for multilingual drafts. The catalogue carries the measured numbers and the known limits of each.

Full catalogue

What the API guarantees

Status labels — MEASURED — exists and was measured on the stated date by the stated method. BUILT — exists and works, not yet measured under load. PLANNED — designed, not yet built. A line without a label is not a claim of this platform.

Errors

Every error is one JSON shape with the HTTP status that names its class. The message never contains URLs, tokens, paths or upstream exception text.

An error response with its headers

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-Request-Id: 5b8e2b2e-4a2f-4b7c-9d2e-1f3a4b5c6d7e
Retry-After: 12

{
  "error": {
    "type": "rate_limit_error",
    "code": "requests_per_minute",
    "message": "Too many requests for this project. Retry after the number of seconds in Retry-After.",
    "request_id": "5b8e2b2e-4a2f-4b7c-9d2e-1f3a4b5c6d7e"
  }
}

Open the API reference