# OpenScale API reference

One API key for open models in the OpenAI Chat Completions, OpenAI Responses and Anthropic Messages formats.

OpenScale serves open models in the API formats your tools already speak: OpenAI Chat
Completions, OpenAI Responses and Anthropic Messages. Point an OpenAI SDK at `https://api.openscale.so/v1`
(or an Anthropic SDK at `https://api.openscale.so/anthropic`), send your OpenScale key, and your existing code
runs unchanged.

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.openscale.so/v1", api_key="sk-openscale-...")
resp = client.chat.completions.create(
    model="deepseek/deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "Hello from OpenScale"}],
)
print(resp.choices[0].message.content)
```

Using a coding agent? The [agent setup guide](https://openscale.so/setup?utm_source=api_reference&utm_medium=docs) has a tested, copy-paste setup for
Claude Code, Codex, OpenCode and the other popular agents.

## Quick start

Create an API key in the dashboard, then send your first request:

```bash
curl https://api.openscale.so/v1/chat/completions \
  -H "Authorization: Bearer $OPENSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "deepseek/deepseek-v4.1-flash",
  "messages": [
    {
      "role": "user",
      "content": "Hello from OpenScale"
    }
  ]
}'
```

## API formats

| Format | Path on `api.openscale.so` | Used by |
| --- | --- | --- |
| OpenAI Chat Completions | `/v1/chat/completions` | OpenAI SDKs, most agents and apps |
| OpenAI Responses | `/v1/responses` | Codex and Responses SDKs |
| Anthropic Messages | `/anthropic/v1/messages` | Claude Code and Anthropic SDKs |

All three share one key, one balance and the same rate limits, prices and cache discounts.
On the Anthropic endpoint, send the key as `x-api-key` or a Bearer token. Any `claude-*`
model name runs DeepSeek V4.1 Flash, so tools that only offer Claude models work as they are;
extended thinking maps to reasoning, and Anthropic server tools (web search, code execution)
are not available. `POST https://api.openscale.so/anthropic/v1/messages/count_tokens` returns the exact count the request is
billed for (images, and models whose tokenizer we do not carry, are estimated).

## Authentication

Create a key in the dashboard ([sign up](https://app.openscale.so/signup?utm_source=api_reference&utm_medium=docs) if you have no account yet) and send it
on every request:

```
Authorization: Bearer sk-openscale-...
```

Keys are shown once when created. A missing or revoked key returns `401`.

An OpenScale Unlimited plan comes with its own keys. Every key has one type, set when you create it:

- **Plan keys** (`sk-openscale-plan-...`) are covered by your plan on its included models while
  the plan is active, and never bill your balance. Any other model, fast mode included, returns
  `400` (`model_not_in_plan`).
- **Pay-as-you-go keys** (`sk-openscale-...`) bill your balance on every model, including the
  plan's models.

Subscribing never changes an existing key. Create keys of either type under API keys in the dashboard.

## Command line

The OpenScale CLI does everything from a terminal: sign in, keys, models, chat, agent setup,
balance, usage and limits. Install it with npm (Node 18 or newer, on macOS, Linux or Windows):

```bash
npm i -g openscale-cli
```

To try it without installing: `npx openscale-cli --help`. No Node? On macOS or Linux:

```bash
curl -fsSL https://openscale.so/install | sh
```

With Homebrew: `brew install afgventura/tap/openscale`.

It installs `openscale` and its short alias `osc`. Then sign in once; the browser opens to
approve this device, and the CLI keeps a key of its own for model calls:

```bash
openscale login
openscale chat "Hello from OpenScale"
openscale setup claude-code
openscale balance
```

`openscale --help` lists every command, and every command takes `--json` for scripts. In CI,
set `OPENSCALE_API_KEY` instead of signing in: models, chat, batch, balance, usage and limits
work with a key alone. Signed-in devices are listed, and can be signed out, in the dashboard's
Settings, Devices. Exit codes: `0` ok, `1` error, `2` usage, `3` sign-in needed, `4` out of
credit, `5` limit reached.

## Reference sections

- [Chat Completions](https://openscale.so/docs/chat-completions): POST /v1/chat/completions: the OpenAI Chat Completions format, streamed or not, with reasoning and tools.
- [Responses](https://openscale.so/docs/responses): POST /v1/responses: the OpenAI Responses format with stored state, background runs and enforced tool rules.
- [Conversations](https://openscale.so/docs/conversations): Keep the turns of a Responses conversation on our side and continue it by id.
- [Prompts](https://openscale.so/docs/prompts): Save instructions, messages and settings once, then use them by id in the Responses API.
- [Anthropic Messages](https://openscale.so/docs/messages): POST /anthropic/v1/messages: the Anthropic Messages format, for Claude Code and Anthropic SDKs.
- [Models and pricing](https://openscale.so/docs/models): Model ids, prices per 1M tokens, context windows, output limits, versions and the live catalog endpoint.
- [Batch](https://openscale.so/docs/batch): Upload a JSONL file of chat completions, create a batch and collect the results when it finishes.
- [Errors](https://openscale.so/docs/errors): The error shape, every status code and code, and which ones to retry.
- [Rate limits](https://openscale.so/docs/rate-limits): Requests and tokens per minute, how a 429 tells you when to retry, and how to get more.
- [Data retention](https://openscale.so/docs/data-retention): What is stored, for how long, how to delete it, and zero data retention.
- [Interactive reference](https://openscale.so/docs/reference): try every endpoint in the browser.
- [OpenAPI document](https://openscale.so/openapi.json): the whole API as OpenAPI 3.1.
