Chat Completions

Generate a model response for a conversation. This is the core endpoint. It follows OpenAI's Chat Completions request and response format, so the OpenAI SDKs work once you set the SovereignEG base URL and API key. Differences to know:

  • Running out of credit returns HTTP 402 (insufficient_quota), not 429.
  • Streamed responses include token usage even if you did not set stream_options (see Streaming).
  • The response model is the id reported by the model that served the request, and it can differ from the id you sent.
  • n is capped at 8.
  • Parameters the gateway does not recognise are ignored rather than rejected.
  • If your balance cannot pay for the full output, max_tokens is lowered and the response carries X-Output-Clamped.
  • Claude models served directly by Anthropic reject OpenAI-only parameters (seed, logprobs, logit_bias, non-zero penalties, n > 1) with a 400.

Endpoint

POST https://backend.sovereigneg.com/v1/chat/completions

Request body

ParameterTypeRequiredDescription
modelstringYesModel ID from GET /v1/models or the Model Library
messagesarrayYesConversation messages (see below)
temperaturefloatNoSampling temperature (0.0–2.0). Default: 1.0
max_tokensintegerNoMax tokens to generate (max_completion_tokens is also accepted and takes precedence). Must not exceed the model's context window (400 max_tokens_exceeded). Default: model-dependent. If your remaining balance cannot pay for the full output, the gateway lowers this cap (or sets one if you sent none) to what the balance can buy and returns X-Output-Clamped: <n>; the reply can then stop early with finish_reason: "length"
top_pfloatNoNucleus sampling (0.0–1.0). Default: 1.0
streambooleanNoStream response via SSE. Default: false
stopstring/arrayNoStop sequences
frequency_penaltyfloatNoFrequency penalty (-2.0 to 2.0). Default: 0.0
presence_penaltyfloatNoPresence penalty (-2.0 to 2.0). Default: 0.0
reasoning_effortstringNoReasoning depth on models that reason: none, minimal, low, medium, high, xhigh. Dropped on models that do not reason and mapped to the nearest value the selected model accepts; see Parameter adjustments below

Parameter adjustments

Agent frameworks send reasoning_effort on every request, including to models that do not reason. Instead of failing the request with the provider's 400, the gateway adjusts the parameter for the selected model and names the adjustment in a response header:

HeaderMeaning
X-Dropped-Params: reasoning_effortThe model does not reason (for example gpt-4o-mini), or its provider has no equivalent of the field (Claude models served directly by Anthropic use thinking budgets instead), so the field was removed before the request reached the provider.
X-Mapped-Params: reasoning_effort=<value>The model reasons but does not accept the value you sent; <value> is what it received (for example none becomes minimal on gpt-5-mini).

Neither header appears when the value went through unchanged. Models served by OpenAI-compatible providers other than OpenAI itself (OpenRouter, DeepInfra, Together and the like) receive the value as sent and never trigger an adjustment. On streaming and non-streaming responses alike, the headers describe the backing that served the request, including after a failover to another backing.

Message roles

RolePurpose
systemSets the behavior of the assistant
developerOpenAI's newer name for system. Claude models served directly by Anthropic treat it as system; other models receive it as sent and whether they honour it depends on the model, so use system when in doubt
userThe human's input
assistantThe model's previous response (for multi-turn), including any tool_calls it made
toolThe result of a tool call; requires tool_call_id (see Function Calling)

Example request

from openai import OpenAI
 
client = OpenAI(
    api_key="sk-...",
    base_url="https://backend.sovereigneg.com/v1"
)
 
response = client.chat.completions.create(
    model="gpt-oss-20b",
    messages=[
        {"role": "system", "content": "You are a concise technical writer."},
        {"role": "user", "content": "Explain how transformers work in 3 sentences."}
    ],
    temperature=0.7,
    max_tokens=256
)
 
print(response.choices[0].message.content)

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711000000,
  "model": "<id reported by the serving model>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Transformers use self-attention mechanisms..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 65,
    "total_tokens": 93
  }
}

model in the response is the id reported by the provider or engine that served the request. It can differ from the id you sent (for example a vendor-prefixed or dated snapshot name), so do not compare it to your request.

Streaming

Set stream: true to receive tokens as server-sent events. See Streaming for details.

Multi-turn conversation

Pass the full conversation history in the messages array:

response = client.chat.completions.create(
    model="gpt-oss-20b",
    messages=[
        {"role": "system", "content": "You are a helpful math tutor."},
        {"role": "user", "content": "What is 15% of 200?"},
        {"role": "assistant", "content": "15% of 200 is 30."},
        {"role": "user", "content": "And 20% of the same number?"}
    ]
)
PreviousAuthenticationNextStreaming