# API quickstart

> Connect to the OpenCheese AI gateway: API host and base URLs, Bearer and x-api-key auth, a first curl request, and every docs page for the API and your tools.
>
> Web page: https://opencheese.dev/en/docs/ · Every docs page: https://opencheese.dev/llms.txt

OpenCheese AI is an AI gateway with OpenAI-compatible and Anthropic-compatible APIs. One
OpenCheese API key reaches every model enabled for your account, including free models, and
every request is recorded with its token usage and cost in the dashboard.

Every page of these docs is also available as Markdown: add `.md` to its address, for example
[/en/docs.md](https://opencheese.dev/en/docs.md) for this page.

## 1. Create an API key

Sign in at [opencheese.dev](https://opencheese.dev/en/), open **API keys** and create a key.
Keep it on the server: never ship a privileged key in public frontend code.

## 2. API host and base URLs

The gateway is served from `https://api.opencheese.dev`, a different host from the website.
Requests sent to `opencheese.dev` return the website, not an API response.

| Client | Base URL |
| --- | --- |
| OpenAI SDKs and OpenAI-compatible clients (OpenCode, Codex, Harness AI, Zed, Chatbox, RikkaHub) | `https://api.opencheese.dev/v1` |
| Anthropic SDKs and Anthropic-compatible clients (Claude Code, Claude Desktop) | `https://api.opencheese.dev` |

Anthropic SDKs append `/v1/messages` themselves, so their base URL must not end in `/v1`. A
few apps ask for the address up to `/v1` even in their Anthropic mode; each app's guide below
says which form it needs.

## 3. Authentication

Send the key as a Bearer token:

```text
Authorization: Bearer YOUR_OPENCHEESE_API_KEY
```

Anthropic-style clients may send it as `x-api-key: YOUR_OPENCHEESE_API_KEY` instead.

The examples read the key from `OPENCHEESE_API_KEY`. The key contains `$` characters, so set
the variable in single quotes, which leave them alone (double quotes would expand them and
break the key):

```bash
export OPENCHEESE_API_KEY='YOUR_OPENCHEESE_API_KEY'
```

In PowerShell: `$env:OPENCHEESE_API_KEY = 'YOUR_OPENCHEESE_API_KEY'`.

## 4. List the models your key can use

```bash
curl https://api.opencheese.dev/v1/models \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

Use an `id` from this list. Access depends on your plan and the key's model restrictions, so
do not copy model IDs from old examples. The [Models API](https://opencheese.dev/en/docs/models.md) page explains
every field.

## 5. Send a first request

OpenAI Chat Completions:

```bash
curl https://api.opencheese.dev/v1/chat/completions \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello"}]}'
```

Anthropic Messages:

```bash
curl https://api.opencheese.dev/v1/messages \
  -H "x-api-key: $OPENCHEESE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
```

With the OpenAI Python SDK:

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
reply = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)
```

## 6. Keep a conversation together

Send the same `opencheese-session-uuid` header with every request of one conversation, so the
dashboard shows it as one session. A request without it is a session of its own. See
[Sessions](https://opencheese.dev/en/docs/sessions.md) for when to send it.

## Endpoints

| Endpoint | Protocol | Use |
| --- | --- | --- |
| `GET /v1/models` | OpenAI | [Models available to the key](https://opencheese.dev/en/docs/models.md) |
| `POST /v1/chat/completions` | OpenAI | [Chat, streaming and tools](https://opencheese.dev/en/docs/chat-completions.md) |
| `POST /v1/responses` | OpenAI Responses | [Responses clients such as Codex](https://opencheese.dev/en/docs/responses.md) |
| `POST /v1/messages` | Anthropic | [Claude Code and Anthropic SDKs](https://opencheese.dev/en/docs/messages.md) |
| `POST /v1/messages/count_tokens` | Anthropic | [Token counting, not billed](https://opencheese.dev/en/docs/messages.md) |
| `POST /v1/images/generations` | OpenAI Images | [Generate images](https://opencheese.dev/en/docs/images.md) |
| `POST /v1/images/edits` | OpenAI Images (multipart) | [Edit images](https://opencheese.dev/en/docs/images.md) |
| `GET /v1/images/capabilities` | OpenCheese | [Image model parameters](https://opencheese.dev/en/docs/images.md) |
| `GET /v1/key` | OpenCheese | [The key's spending limit and usage](https://opencheese.dev/en/docs/account.md) |
| `GET /v1/plan` | OpenCheese | [Plan windows and balance options](https://opencheese.dev/en/docs/account.md) |
| `GET /v1/balance` | OpenCheese | [Balance and this month's usage](https://opencheese.dev/en/docs/account.md) |

Capabilities such as streaming, tools, image input and reasoning levels vary by model: check
the model in `/v1/models` before depending on one.

## Every page

### Get started

- [Sessions](https://opencheese.dev/en/docs/sessions.md): One conversation, one session: the opencheese-session-uuid header.

### API reference

- [Models](https://opencheese.dev/en/docs/models.md): GET /v1/models and what each field means.
- [Chat Completions](https://opencheese.dev/en/docs/chat-completions.md): POST /v1/chat/completions: streaming, tools, images, effort.
- [Responses](https://opencheese.dev/en/docs/responses.md): POST /v1/responses: input, streaming events, tools.
- [Messages](https://opencheese.dev/en/docs/messages.md): POST /v1/messages and /v1/messages/count_tokens.
- [Images](https://opencheese.dev/en/docs/images.md): Generate and edit images with the OpenAI Images API.
- [Key, plan and balance](https://opencheese.dev/en/docs/account.md): GET /v1/key, /v1/plan and /v1/balance.
- [Errors and limits](https://opencheese.dev/en/docs/errors.md): Error shapes, codes, rate limits and retries.

### Coding tools

- [Claude Code](https://opencheese.dev/en/docs/claude-code.md): ANTHROPIC_BASE_URL, API key and model aliases in settings.json.
- [Claude Desktop](https://opencheese.dev/en/docs/claude-desktop.md): Third-party inference mode with an imported configuration file.
- [Codex](https://opencheese.dev/en/docs/codex.md): A config.toml model provider on the Responses API.
- [OpenCode](https://opencheese.dev/en/docs/opencode.md): Auto-sync, or an OpenAI-compatible provider in opencode.json.
- [Harness AI](https://opencheese.dev/en/docs/harness-ai.md): A custom provider, plus reasoning levels in settings.yaml.
- [Zed](https://opencheese.dev/en/docs/zed.md): An openai_compatible provider in settings.json.
- [VS Code and JetBrains](https://opencheese.dev/en/docs/ide.md): The Claude Code and Codex extensions, on the CLI settings.

### Chat apps

- [RikkaHub](https://opencheese.dev/en/docs/rikkahub.md): An OpenAI or Claude provider in the Android app.
- [Chatbox](https://opencheese.dev/en/docs/chatbox.md): An OpenAI API compatible provider, on phone or desktop.
- [LobeHub](https://opencheese.dev/en/docs/lobehub.md): A provider entry with the right address for each format.

## Errors

Most errors return an HTTP status with a JSON error body. On `/v1/chat/completions`, problems
you need to act on (an invalid key, a plan limit, an empty balance) arrive as the assistant's
reply so chat apps show the message to you. [Errors and rate limits](https://opencheese.dev/en/docs/errors.md) lists
every code.

## Plans and prices

Plans are listed on the [home page](https://opencheese.dev/en/#pricing). Per-model prices are on
the dashboard's **Prices** page after you sign in.

## More help

- [FAQ](https://opencheese.dev/en/faq/): setup, models, plans, payments and troubleshooting.
- Support Chat in the dashboard, or service@opencheese.dev.