Protocol guide
OpenAI-compatible base URLs, explained
What an OpenAI-compatible base URL is, how SDKs append /chat/completions, the double and missing /v1 mistakes, and where each coding tool keeps it.
An OpenAI-compatible base URL is the address a client puts in front of every API path it calls. The client appends /chat/completions, /responses or /models to it, so the base URL must end exactly where those paths begin — for ScaleMax, https://api.scalemax.pro/v1.
What a base URL is
The OpenAI SDKs, and the many tools that copy their conventions, never take a full endpoint address. They take a base URL and an API key, then build each request themselves. Changing the base URL is what moves a client from OpenAI to another OpenAI-compatible provider — the request body, the response and the model field keep the same shape.
The SDKs also read it from the environment: OPENAI_BASE_URL for the official Python and Node SDKs, while some tools use their own name, such as Aider’s OPENAI_API_BASE.
How clients build the full URL
| Call | Path the client appends | Full URL on ScaleMax |
|---|---|---|
| Chat Completions | /chat/completions | https://api.scalemax.pro/v1/chat/completions |
| Responses | /responses | https://api.scalemax.pro/v1/responses |
| List models | /models | https://api.scalemax.pro/v1/models |
| Anthropic Messages (Anthropic SDK, Claude Code) | /v1/messages | https://api.scalemax.pro/v1/messages |
The last row is why Anthropic-style clients take the origin, https://api.scalemax.pro, with no /v1: they append /v1/messages themselves. Same host, two conventions.
OpenAI-compatible, Pay as you go key: https://api.scalemax.pro/v1
OpenAI-compatible, token pack key: https://api.scalemax.pro/token/v1
Anthropic origin: https://api.scalemax.pro (token pack: https://api.scalemax.pro/token)
The three common mistakes
1. A doubled /v1
Putting https://api.scalemax.pro/v1 into an Anthropic-style field produces /v1/v1/messages, which fails with a not-found error. Anthropic-style fields take the origin.
2. A missing /v1
Putting the bare origin into an OpenAI-style field produces https://api.scalemax.pro/chat/completions. Some tools add /v1 for you and some do not; when in doubt, include it.
3. A base URL that does not match the key
ScaleMax has two billing modes on two routes. A token pack key belongs on /token/v1; a Pay as you go key on /v1. The model list may load on the wrong route and chat still fail, which looks like an authentication problem.
Also avoid pasting the endpoint itself (…/chat/completions) as the base URL, and trailing spaces — both are common copy-paste errors.
Where each tool keeps it
| Tool | Setting |
|---|---|
| Cursor | Settings → Models → custom OpenAI-compatible model: base URL |
| Cline / Roo Code | API provider “OpenAI Compatible” → Base URL |
| Kilo Code | Providers → Custom provider → Base URL |
| Continue | apiBase in config.yaml |
| OpenCode | options.baseURL in opencode.json |
| Aider | OPENAI_API_BASE environment variable |
| Zed | api_url under language_models.openai_compatible |
| Codex CLI | base_url of the provider in config.toml |
| Claude Code | ANTHROPIC_BASE_URL — the origin, no /v1 |
Check it in one command
List the models your key can use. If this works, the base URL and key are right; then use one of the returned IDs.
curl https://api.scalemax.pro/v1/models \
-H "Authorization: Bearer $SCALEMAX_API_KEY"For a token pack key, use https://api.scalemax.pro/token/v1/models. Chat requests are billed at the model’s published rate.