Model gateway

Gateway API

Reference for the OpenAI-compatible endpoints at www.scalaix.com/v1, with Scalaix headers and errors.

Base URL: https://www.scalaix.com/v1. Authenticate with Authorization: Bearer sx_.... Requests and responses follow the OpenAI API, so existing clients work unchanged.

GET /v1/models

Lists the models the key may use, in the OpenAI list shape. Each entry has a scalaix object with the provider, billed prices per million tokens (margin included), limits and capabilities. When routing is possible for the key, the list also contains {"id": "auto"}.

curl https://www.scalaix.com/v1/models -H "Authorization: Bearer $SCALAIX_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "owned_by": "open_ai",
      "scalaix": {
        "provider": "open_ai",
        "input_per_mtok": 0.15,
        "output_per_mtok": 0.6,
        "context_window": 128000,
        "max_output_tokens": 16384,
        "supports": ["text", "vision", "json"]
      }
    },
    { "id": "auto" }
  ]
}

POST /v1/chat/completions

The OpenAI chat completions request and response, streaming or not.

curl https://www.scalaix.com/v1/chat/completions \
  -H "Authorization: Bearer $SCALAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Answer in one sentence."},
      {"role": "user", "content": "What is a circuit breaker?"}
    ],
    "temperature": 0.3
  }'

Supported fields

Field	Notes
`model`	A catalog id, `auto` (routing), or `default` (the key's default model). Omit it to use the default.
`messages`	Roles `system`, `developer`, `user`, `assistant`, `tool`. Text and `image_url` content parts.
`temperature`, `top_p`, `seed`, `stop`, `user`	Passed to the provider.
`max_tokens`, `max_completion_tokens`	Either one.
`n`	Any value for OpenAI-compatible providers; only `1` for Anthropic models.
`response_format`	`text`, `json_object` or `json_schema`.
`tools`, `tool_choice`	Function calling.
`stream`, `stream_options.include_usage`	Server-sent events ending with `data: [DONE]`.

Responses always include usage. When streaming, ask for stream_options: {"include_usage": true} to get it as a final chunk.

Streaming

curl -N https://www.scalaix.com/v1/chat/completions \
  -H "Authorization: Bearer $SCALAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "stream": true, "stream_options": {"include_usage": true},
       "messages": [{"role": "user", "content": "Count to five."}]}'

Structured output

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "Extract the city: I live in Lisbon."}],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "city",
      "schema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"],
        "additionalProperties": false
      }
    }
  }
}

Headers

Request

Header	Meaning
`Authorization: Bearer sx_...`	Required.
`X-Scalaix-Cache: off`	Skip the cache for this request.
`X-Scalaix-Cache: ttl=<seconds>`	Cache this request's answer for this many seconds.

Response

Header	Meaning
`X-Scalaix-Request-Id`	On every response. Quote it when you contact support.
`X-Scalaix-Model`	The model that answered (after routing and fallback).
`X-Scalaix-Cache`	`hit`, `miss` or `off`.
`X-Scalaix-Fallbacks`	How many fallback models were tried before the answer.
`Retry-After`	On `429`: seconds to wait.

Errors

Errors use the OpenAI shape:

{ "error": { "message": "Model claude-3-opus is not allowed for this key.", "type": "forbidden", "code": "forbidden" } }

Status	`type`	When
400	`invalid_request`	The body isn't valid.
401	`invalid_api_key`	Missing, unknown, revoked or expired key.
402	`insufficient_quota`	The team is out of credits, or the key's monthly budget can't cover the request (see Budgets).
403	`forbidden`	The key's rules don't allow this model, collection, origin, IP or mode.
404	`not_found`	Unknown model or path.
413	`invalid_request`	The body is over 10 MB.
429	`rate_limited`	Over the key's requests per minute. See `Retry-After`.
501	`not_implemented`	A feature that isn't available yet.
502	`upstream_error`	The provider failed and no fallback succeeded.
504	`timeout`	The provider didn't answer in time.

See Errors for handling advice.