Create a chat completion (OpenAI-compatible)

Generates a model response for a conversation. Drop-in for the OpenAI Python or TypeScript SDK — set base_url="https://api.stav.ai/v1" and your existing code works.

Supports streaming via SSE (stream=true), function calling (tools[]), structured output (response_format), extended thinking (reasoning_effort), and prompt caching markers (cache_control on messages, tools and the system prompt, where the underlying model supports it).

Pass model="auto" to invoke the Smart Router, or @workspace-slug/router-slug to use one of your workspace's named routers.

tools[] are your own functions: Stav returns the call the model wants to make and your application executes it. Stav does not run tools server-side.

Request bodyapplication/json

• modelstringrequired

  One of these forms:

  • creator/model — a catalogue model; the Smart Router picks the Provider Endpoint among those your policy admits;
  • creator/model/provider — the same model pinned to one Inference Provider (add :tier, e.g. :fast, to pin a serving tier). A pin never bypasses your policy: an endpoint the model lacks is a 404, one your policy excludes is a 403, both by name;
  • the bare model name (claude-opus-5) — a convenience alias, accepted when it names exactly one catalogue model;
  • auto — your workspace's default routing policy;
  • @workspace-slug/router-slug — a named router your workspace authored;
  • creator/model/@node — the same model pinned to one of your own Stav Tunnel nodes (@workspace-slug/node also works). A model your node serves that is not in the catalogue is named @workspace-slug/local-id and pinned as @workspace-slug/local-id/@node. A pin to a node never fails over; auto and router traffic does.
• messagesarray of objectsrequired
  Show 5 child fields

  • roleenumrequired
    systemuserassistanttool
  • contentstring | array of object

    String for text-only messages, or array of content parts (text, image_url, input_audio) for multimodal models.

  • namestring

    Optional name for the message author.

  • tool_call_idstring

    Required when role is tool.

  • tool_callsarray of objects

    Tool calls the assistant made (assistant-role messages only).

    Show 3 child fields

    • idstringrequired
    • typestringrequired
    • functionobjectrequired
      Show 2 child fields

      • namestringrequired
      • argumentsstringrequired

        JSON-encoded argument object.

• streamboolean
  Default: false
• stream_optionsobject

  Streaming options, applied only when stream=true.

  Show 1 child field

  • include_usageboolean

    When true, a final SSE chunk carries a usage object with token counts and an empty choices array, before the [DONE] sentinel. Without it a streaming response reports no token counts at all.

• ninteger

  Number of choices to return. Only 1 is supported — n>1 returns 400 (unsupported_parameter). Issue parallel requests instead.

  Default: 1
• providerobject

  Stav extension. Narrows which providers may serve an explicitly pinned model. Not applied on the auto or named-router path — shape those with workspace policy and router allowlists instead.

  Show 7 child fields

  • onlyarray of string

    Provider allowlist.

  • ignorearray of string

    Provider blocklist.

  • max_priceobject

    Per-1M-token EUR ceiling.

    Show 2 child fields

    • promptnumber
    • completionnumber
  • quantizationsarray of string
  • sort

    Not supported. Sending it returns 400 unsupported_parameter with param provider.sort.

  • require_parameters

    Not supported. Sending it returns 400 unsupported_parameter with param provider.require_parameters.

  • allow_fallbacks

    Not supported. Sending it (true or false) returns 400 unsupported_parameter with param provider.allow_fallbacks.

• modelsarray of string

  Stav extension, reserved for a later release. Accepted on auto or a Router and has no effect today. With an explicit model it returns 400 unsupported_parameter (param models).

• temperaturenumber

  Sampling temperature. Higher is more random. Honoured on: OpenAI, Anthropic, Google, Mistral.

• top_pnumber

  Nucleus sampling cutoff. Honoured on: OpenAI, Anthropic, Google, Mistral.

• max_tokensinteger

  Maximum tokens to generate. Honoured on: OpenAI, Anthropic, Google, Mistral.

• response_formatobject

  Structured-output contract (json_object / json_schema). type grammar is refused (400). Honoured on: OpenAI, Anthropic, Google, Mistral. Requires the structured_output capability — with model="auto" this becomes a hard filter on the candidate pool.

  Show 3 forms

  ResponseFormatText

  • typestringrequired

  ResponseFormatJsonObject

  • typestringrequired

  ResponseFormatJsonSchema

  • typestringrequired
  • json_schemaobjectrequired
    Show 4 child fields

    • namestringrequired
    • schemarequired

      A JSON Schema 2020-12 document.

    • descriptionstring
    • strictboolean
      Default: false
• toolsarray of objects

  Function/tool definitions the model may call. Hosted tools (any type other than function or custom, e.g. web_search) are dropped and named in X-Stav-Dropped-Params: no provider on this surface runs them. Honoured on: OpenAI, Anthropic, Google, Mistral. Requires the function_calling capability — with model="auto" this becomes a hard filter on the candidate pool.

  Show 2 child fields

  • typestringrequired
  • functionobjectrequired
    Show 3 child fields

    • namestringrequired
    • descriptionstring
    • parameters

      JSON Schema for the function's arguments.

• allowed_toolsarray of string | object

  Restrict which of tools the model may call, without changing the tool array — so a mid-loop restriction does not invalidate the prompt cache. The value is passed to the provider as sent. Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral. Requires the function_calling capability — with model="auto" this becomes a hard filter on the candidate pool.

• tool_choiceenum | object

  Constrain which tool the model may call. Honoured on: OpenAI, Anthropic, Google, Mistral. Requires the function_calling capability — with model="auto" this becomes a hard filter on the candidate pool.

  Show 1 form

  ToolChoiceFunction

  • typestringrequired
  • functionobjectrequired
    Show 1 child field

    • namestringrequired
• reasoning_effortenum

  Reasoning depth for models that support extended thinking (none, minimal, low, medium, high, xhigh, max). none asks a model that reasons by default to stop; it does not require the extended_thinking capability. Translated to the nearest level the serving endpoint accepts (ties round down); the level sent is returned in X-Stav-Reasoning-Effort. Honoured on: OpenAI, Anthropic, Google, Mistral. Aliases accepted: reasoning, thinking. Any level other than none requires the extended_thinking capability — with model="auto" this becomes a hard filter on the candidate pool.

  noneminimallowmediumhighxhighmax
• stopstring | array of string

  Up to 4 sequences that halt generation. Honoured on: OpenAI, Anthropic, Google, Mistral.

• top_kinteger

  Top-k sampling cutoff. Honoured on: Anthropic, Google. Returns 400 unsupported_parameter on: OpenAI, Mistral.

• seedinteger

  Best-effort determinism across identical requests. Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• logprobsboolean

  Return log probabilities for output tokens. Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• top_logprobsinteger

  Most-likely tokens to return per position (0–20). Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• presence_penaltynumber

  Penalise tokens already present in the text. Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• frequency_penaltynumber

  Penalise tokens by existing frequency. Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• logit_biasobject

  Per-token likelihood bias map (token id → −100..100). Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• verbosityenum

  GPT-5 output verbosity hint (low / medium / high). Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

  lowmediumhigh
• predictionobject

  Predicted output for latency-optimised edits (OpenAI). Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• prompt_cache_keystring

  Cache-routing hint for OpenAI automatic prompt caching. Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• safety_identifierstring

  Stable end-user identifier for abuse monitoring. Honoured on OpenAI; declared intentional-ignore elsewhere (portable clients send it universally). Honoured on: OpenAI. Declared no-op on: Anthropic, Google, Mistral (accepted and ignored, never a 400).

• service_tierenum

  OpenAI processing tier (auto / default / flex / priority). Billing follows the tier the provider echoes, not the one sent (auto may come back as priority); the request log shows it. A tier the endpoint has no conditional rate for is refused with 400 service_tier_unpriced (the message names the tier); auto is accepted only when every tier the provider may pick is priced (issue #1154 gap 4). Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

  autodefaultflexpriority
• userstring

  Stable end-user identifier (legacy; see safety_identifier). Honoured on OpenAI; declared intentional-ignore elsewhere (OpenAI-SDK clients attach it to every request, any provider). Honoured on: OpenAI. Declared no-op on: Anthropic, Google, Mistral (accepted and ignored, never a 400).

• parallel_tool_callsboolean

  Allow the model to emit multiple tool calls in one turn. Honoured on: OpenAI. Returns 400 unsupported_parameter on: Anthropic, Google, Mistral.

• min_pnumber

  Min-p nucleus floor. Provider-specific tuning. Not honoured on any provider — returns 400 unsupported_parameter naming the parameter and the model that resolved.

• repetition_penaltynumber

  Repetition penalty. Provider-specific tuning. Not honoured on any provider — returns 400 unsupported_parameter naming the parameter and the model that resolved.

• storeboolean

  Persist the completion for later retrieval. false is accepted: Stav never persists completions. true would store your output in Stav's provider account, not yours. true returns 400 unsupported_parameter on every provider, naming the parameter and the model that resolved.

• session_idstring

  Stav extension — explicit conversation session id (overrides anchor chaining). Also names the routing session: the router uses it to remember what it decided last turn, for sticky routing and warm caches. Namespaced by team and API key before hashing, so two tenants sending default never share state. Also accepted as the X-Session-Id request header; the resolved session is echoed back in the X-Session-Id response header. Meant for Stav's router and forwarded to no provider — accepted on every model, never a 400.

• cost_tierenum

  Stav extension, reserved for a later release. Accepted and checked (an unknown value is a 400), and has no effect today. Meant for Stav's router and forwarded to no provider — accepted on every model, never a 400.

  lowbalancedhighmax
• remaining_turnsinteger

  Stav extension, reserved for a later release. Accepted and checked (outside 0–1000 is a 400), and has no effect today. Meant for Stav's router and forwarded to no provider — accepted on every model, never a 400.

• metadataobject

  Free-form tags on a stored completion. Tied to store. Not honoured on any provider — returns 400 unsupported_parameter naming the parameter and the model that resolved.

• modalitiesarray of string

  Requested output modalities (e.g. audio). Stav serves text. Not honoured on any provider — returns 400 unsupported_parameter naming the parameter and the model that resolved.

• include_reasoningboolean

  Echo the reasoning trace in the response. Reasoning is reported as a token count on usage.completion_tokens_details instead. Not honoured on any provider — returns 400 unsupported_parameter naming the parameter and the model that resolved.

• chat_template_kwargsobject

  Backend chat-template arguments. Not honoured on any provider — returns 400 unsupported_parameter naming the parameter and the model that resolved.

Notes

Many gateways accept every parameter and quietly drop the ones the upstream model cannot use. You get a 200 and the setting did nothing.

Stav does the opposite:

A parameter is either honoured, or refused by name with a 400. It is never silently dropped.

If a provider cannot honour a parameter, the request is refused. Where something must be removed to make the request work — a hosted tool no provider runs, or a cache marker on the translation path — the response names it in X-Stav-Dropped-Params.

This page covers /v1/chat/completions, where the contract is enforced by one parameter registry. /v1/messages and /v1/responses are covered at the end.

What a refusal looks like

{
  "error": {
    "message": "Parameter 'logit_bias' is not supported by provider 'anthropic'. Remove it or route to a model/provider that supports it.",
    "type": "invalid_request_error",
    "param": "logit_bias",
    "code": "unsupported_parameter",
    "request_id": "chatcmpl-…",
    "docs_url": "https://stav.ai/docs/api/errors#request-validation"
  }
}

When the limit belongs to the model rather than the provider — stop on an OpenAI GPT-5 or o-series model, for example — the message names the model, and the router and model you asked for if they differ:

Parameter 'stop' is not supported by model 'gpt-5-5'. Remove the parameter, or address a
model served by a provider that supports it (anthropic, google, mistral, openai).

A field the request schema does not know is also a 400 naming the field.

Discover before you send

• GET /v1/params — the registry as JSON: every parameter, its description, the dialects that honour it, and the capability it needs. Anonymous, no key required.
• GET /v1/models/{id} — stav_capabilities for one model (tool_use, vision, structured_output, extended_thinking, …) and stav_supports_thinking.

curl https://api.stav.ai/v1/params
curl https://api.stav.ai/v1/models/anthropic/claude-sonnet-4-5 \
  -H "Authorization: Bearer $STAV_API_KEY"

When you route with model="auto" or a Router, the capabilities your request needs (tools, images, a schema, reasoning) become hard filters on the candidate pool.

Dialects, not providers

Support is keyed by wire dialect:

The table

Legend: ✅ honoured · 400 refused by name · ignored accepted and not forwarded, by design

model, messages, stream and stream_options are request structure, not parameters. stream_options.include_usage is honoured on every dialect.

Stav extensions

Read by Stav, never forwarded to a provider.

See Routing hints. models, cost_tier and remaining_turns are reserved for a later release: they are accepted and have no effect today (models with a named model is a 400 unsupported_parameter).

Refused by name. These parse, but nothing honours them, so each returns 400 unsupported_parameter with param set to the field: provider.sort, provider.require_parameters, provider.allow_fallbacks, and response_format with type: "grammar".

Dropped, and named

Four things are removed rather than refused, because leaving them in would break the request.

Sampling a model does not take. Some Provider Endpoints accept only the default temperature and top_p. Stav measures this per endpoint, from the provider's own error. A non-default value there is left out and named in X-Stav-Dropped-Params, so SDK defaults such as temperature=0.7 keep working.

A reasoning level on a model that does not reason. On /v1/chat/completions, when you name a model that cannot reason, reasoning_effort (or reasoning / thinking) is left out and named in X-Stav-Dropped-Params. The answer is the same either way: the model does not think. Many agents send a level on every request, so this keeps them working on every model. none is never named — it asks for no reasoning, which the model already does. With auto or a Router, a level still limits the choice to models that reason; see Reasoning.

Hosted tools. Tools that ask the server to run something (web_search, file_search, code_interpreter, Anthropic's web_search_20250305, bash_20250124, …) are not run by any provider behind these surfaces. They are dropped and named in X-Stav-Dropped-Params:

• /v1/chat/completions: every tool whose type is not function or custom.
• /v1/messages with a non-Claude model: every tool whose type is not custom.
• /v1/responses with a model served through translation: hosted tools such as web_search.

If tool_choice points at a dropped tool, or requires a tool when none is left, it is dropped too.

cache_control. It sits inside messages, tools and the system prompt:

On /v1/messages with a non-Claude model it is dropped and named in X-Stav-Dropped-Params.

Lowered, and named

max_tokens above the Provider Endpoint's output limit. max_tokens is a ceiling, and some Provider Endpoints have a lower one — Scaleway serves GLM-5.2 with at most 16,384 output tokens. Stav sends the endpoint's own limit instead and names it in X-Stav-Clamped-Params, for example max_tokens=16384. The answer is the one the provider would give at its own limit. When Stav does not know the limit yet, it learns it from the provider's refusal and retries once at the stated limit; later requests are lowered before the call. A context-length error is not an output limit and is never read as one.

Other surfaces

/v1/messages. Claude models are proxied to Anthropic as sent; unknown fields are forwarded, not refused. Other models are translated onto the chat path: thinking becomes reasoning_effort, and the chat-completions rules above apply. session_id and provider are accepted here too. provider follows the chat-completions rules on every model, including Claude, and is never forwarded to Anthropic.

/v1/responses. OpenAI models are proxied as sent. Other models are translated onto the chat path. store: true is refused (403 store_not_permitted) when your workspace requires zero data retention.

/v1/audio/transcriptions. A multipart/form-data request with its own short list: file, model, language, prompt, response_format, temperature. The same contract applies — any other field, and stream, is refused by name with 400 unsupported_parameter. auto and Routers are refused (router_not_supported). See Audio transcriptions.

Streaming and errors

A refusal found before dispatch is a normal 400. An error after a stream has opened arrives as an SSE error frame followed by a chunk with finish_reason: "error" — the status line already said 200. Check every frame. See Errors.

Response headers

Errors

Every error code, what it means and what to do: Errors.