# Model API

> Base URL, authentication, model ids, errors and rate limits of the OpenAI-compatible Model API.

The Model API is OpenAI-compatible. Point an OpenAI SDK at the base URL, send your key and Account ID, and use the model ids below.

```text
https://api.gateway.clatterlabs.xyz/v1
```

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/models` | The model ids with prices (no key needed) |
| `GET` | `/v1/models/{id}` | One model |
| `POST` | `/v1/chat/completions` | A chat completion, streamed or not, with tools and `usage` |

## Authentication

<ParamField header="Authorization" type="string" required>
`Bearer clsk_...`: an API key with the **models:invoke** permission ([Console › API keys](https://console.clatterlabs.com/api-keys), preset **Model API**).
</ParamField>
<ParamField header="X-Clatter-Account" type="string" required>
The Account ID that owns the key, like `CL-7K2M9QXA` (Console › Settings). With an OpenAI SDK, send it as a default header.
</ParamField>

## Models

| Model id | Model | Effort | Input / 1M tokens | Output / 1M tokens |
| --- | --- | --- | --- | --- |
| `supercosmos-flash` | SuperCosmos | Flash | $1.60 | $3.40 |
| `supercosmos-max` | SuperCosmos | Max | $1.80 | $3.80 |
| `supercosmos-heavy` | SuperCosmos | Heavy | $2.00 | $4.40 |

**Long-context input above 262K tokens: 1.5×** (SuperCosmos): a request whose prompt is over 262K tokens bills its whole input at 1.5× the rate above.

The family id `supercosmos` with `effort` (or `reasoning_effort` `low` / `medium` / `high`) works too. Line Code ids answer `410 model_retired` ([details](/models/line-code-retired)).

## Errors

Errors use the OpenAI shape: `{"error": {"message", "type", "code", "param"}}`. Every response has an `X-Request-Id`.

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request`, `invalid_json`, `unsupported_content`, `unsupported_parameter`, `invalid_effort` | The request isn't valid |
| 401 | `invalid_api_key`, `expired_api_key`, `missing_account_id`, `account_mismatch` | Key or Account ID problem |
| 402 | `out_of_credits` | Trial and credit balance used up |
| 403 | `insufficient_scope` | The key lacks `models:invoke` |
| 404 | `model_not_found`, `not_supported` | Unknown model or endpoint |
| 413 | `request_too_large` | Over 3 MB or 800 messages |
| 429 | `rate_limited` | The key's per-minute limit; see `Retry-After` |
| 502 / 503 / 504 | `model_overloaded`, `model_unavailable`, `model_timeout`, `empty_response`, `stream_error` | Retry with backoff; `Retry-After` when sent |

A stream that fails midway sends `data: {"error": {...}}` and then `data: [DONE]`.

## Rate limits

Each key has its own limit (10, 30, 60 or 120 requests per minute). Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`.