OpenAI SDK migration

Change two lines

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["STAV_API_KEY"],   # sk_stav_live_...
    base_url="https://api.stav.ai/v1",    # was https://api.openai.com/v1
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.STAV_API_KEY,
  baseURL: "https://api.stav.ai/v1",
});

These work through the SDK:

Model names

Catalogue ids are creator/model. Four forms work in model:

model="auto"                              # Smart Router, your workspace default Router
model="@acme/eu-only"                     # a named Router
model="openai/gpt-4o-mini"                # a model; the router picks the Provider Endpoint
model="gpt-4o-mini"                       # bare name, resolved when it is unambiguous

A bare name resolves through the model's aliases, then through a unique match on the last segment. If two creators share it, it resolves to nothing — use the full id. client.models.list() returns what your key can call.

For a first migration, auto is usually the right choice: you get failover and a sovereignty floor without hard-coding a model.

Scopes

A key with no scopes can call everything. A key with scopes needs one per endpoint:

Many IDEs and agent tools fill their model picker from /v1/models. If you scope a key, include inference:models.

What behaves differently

Stav refuses what it cannot honour, by name, instead of dropping it. Expect a few 400s on day one.

See Request parameters for the full list.

Streaming

stream = client.chat.completions.create(
    model="auto",
    messages=messages,
    stream=True,
    stream_options={"include_usage": True},   # needed for token counts
)

Check each chunk for an error key: an error after the stream has started arrives as an SSE frame, not an HTTP status.

See what served the request

raw = client.chat.completions.with_raw_response.create(model="auto", messages=messages)
print(raw.headers.get("X-Stav-Request-Id"))
print(raw.headers.get("X-Stav-Model"))              # the model that answered
print(raw.headers.get("X-Stav-Sovereignty-Level"))  # L0–L4 of the Provider Endpoint
print(raw.headers.get("X-Stav-Route-Reason"))       # set when routed

See Response headers.

The Responses API

POST /v1/responses accepts auto, Routers and any catalogue model. There are two paths:

On the translated path:

• store: true and previous_response_id are refused. Send the full input every turn.
• Hosted tools such as web_search are left out and named in X-Stav-Dropped-Params.
• parallel_tool_calls: false and include entries cannot be carried and are named in the same header.

On the proxied path, store defaults to false, not OpenAI's true. Nothing is kept at the provider unless you send store: true — and a workspace that requires zero data retention refuses that with 403 store_not_permitted.

r = client.responses.create(model="openai/gpt-5.3-codex", input="…", store=True)
client.responses.retrieve(r.id)

retrieve, delete, cancel and input_items.list work for stored OpenAI responses only.

Codex

Codex speaks only the Responses API. In ~/.codex/config.toml:

model = "openai/gpt-5.3-codex"
model_provider = "stav"

[model_providers.stav]
name = "Stav"
base_url = "https://api.stav.ai/v1"
env_key = "STAV_API_KEY"
wire_api = "responses"

Any catalogue model, auto or a Router works as model. Codex sends store: false, so the translated path works for non-OpenAI models.

Migration checklist

1. Create a sk_stav_test_ key.
2. Point one non-critical service at https://api.stav.ai/v1.
3. Run your tests and fix the 400s.
4. Try model="auto" and compare on your own evaluation set.
5. Set a sovereignty floor for the workspace and check X-Stav-Sovereignty-Level.
6. Roll out with a sk_stav_live_ key.

Not available

• Assistants, threads, vector stores, files, batch.
• Image generation, audio inside chat, realtime voice, and moderation. (Transcription and text-to-speech are served — see the two Audio pages.)
• Rerank.

Next steps

• Tools & structured output
• Smart Router
• Errors