# cerber — LLM proxy usage

cerber is a multi-provider proxy that speaks both the OpenAI and the
Anthropic API dialects and routes each request to the right upstream.

## Base URL

    https://cerber.ihatebot.com

## Authentication

- From the local network: no key required.
- From outside: send `Authorization: Bearer <YOUR_KEY>` (or `x-api-key: <YOUR_KEY>`).
  Ask the operator for a key; keys are managed in the dashboard.

## Endpoints

- `POST /v1/chat/completions` — OpenAI-compatible chat (all providers, incl. Claude). Point any OpenAI SDK at base_url `https://cerber.ihatebot.com/v1`.
- `POST /v1/messages` — Anthropic-native messages. Point the Anthropic SDK at base_url `https://cerber.ihatebot.com`.
- `POST /v1/messages/count_tokens` — Anthropic token counting.
- `POST /v1/images/generations` — image generation (OpenAI Images shape; e.g. `grok-imagine-image`).
- `POST /v1/embeddings` — OpenAI embeddings (passthrough to the provider serving the model).
- `POST /v1/completions` — legacy OpenAI text completions (passthrough).
- `POST /v1/responses` — OpenAI Responses API (passthrough; supports streaming).
- `GET /v1/models` — list available model ids (use these exact strings as `model`).
- `GET /llm.md` — this document. `GET /docs` — full HTML reference of every mechanic.

Embeddings/completions/responses are served only by OpenAI-compatible providers (OpenAI/Grok/ollama), not Anthropic; an unsupported model → 400/501.

## Recommended models

- Default: `claude-sonnet-5` (strong; works on `/v1/chat/completions` and `/v1/messages`).
- Most capable: `claude-opus-4-8`.
- Cheap/fast: `claude-haiku-4-5-20251001`.
- Local/free: an ollama model from the list below.
Always set `model` to an exact id (see `GET /v1/models` or the list below). Streaming: add `"stream": true`.

## Picking a specific account / subscription

Send header `X-Cerber-Cred: <value>` to pin which credential serves the request: `oauth` (a subscription token), `key` (an API key), or an exact account name from `GET /admin/accounts`. Omit it to let cerber rotate.

## Automatic fallback (OpenAI endpoint)

On `POST /v1/chat/completions`, if the chosen model fails with a retryable error (provider 5xx, or all accounts rate-limited/unavailable) cerber transparently retries the next model in a fallback chain before any bytes are sent. 4xx client errors are returned as-is. Override per request with header `X-Cerber-Fallback: model2,model3` (comma-separated; each routed like any model, so it may cross providers). No server-side chains are configured; use the header.

## Rate limits & budgets

Your key may carry a cost budget and request/token rate limits. If you hit them you'll get **402** (budget exhausted) or **429** (rate limit) with a JSON error — back off or ask the operator to raise the limit. Limits reset on a rolling window (minute/hour/day/week/month).

## Model routing

Just set `model`; cerber routes by name:

- `gpt*`, `o1*`, `o3*`, `o4*`, `chatgpt*` → OpenAI
- `gemini*` → Gemini
- `grok*` → xAI (Grok)
- `claude*` → Anthropic (Claude)
- the local models listed below → ollama
- anything else → 400 (unknown model)

## Available models

### anthropic (3)

- `claude-haiku-4-5-20251001`
- `claude-opus-4-8`
- `claude-sonnet-5`

### arliai (59)

- `GLM-4.6-Derestricted-v5`
- `GLM-4.7`
- `Gemma-4-31B-Claude-4.6-Opus-Reasoning-Distilled`
- `Gemma-4-31B-Cognitive-Unshackled`
- `Gemma-4-31B-DarkIdol`
- `Gemma-4-31B-Fabled`
- `Gemma-4-31B-Garnet`
- `Gemma-4-31B-GarnetV2`
- `Gemma-4-31B-Gembrain`
- `Gemma-4-31B-Gembrain-uncensored-heretic`
- `Gemma-4-31B-Gemopus`
- `Gemma-4-31B-K1-v5`
- `Gemma-4-31B-Larkspur-v0.5`
- `Gemma-4-31B-Mero-Artemis-v0.3.1`
- `Gemma-4-31B-MeroMero`
- `Gemma-4-31B-Musica-v1`
- `Gemma-4-31B-Queen`
- `Gemma-4-31B-SDFT-Heretic-RP`
- `Gemma-4-31B-Sphinsikus-Chronist`
- `Gemma-4-31B-it`
- `Mistral-Medium-3.5-128B`
- `Qwen3.5-27B-Anko`
- `Qwen3.5-27B-BlueStar-Derestricted`
- `Qwen3.5-27B-BlueStar-Derestricted-Lite`
- `Qwen3.5-27B-BlueStar-v2-Derestricted`
- `Qwen3.5-27B-BlueStar-v2-Derestricted-Lite`
- `Qwen3.5-27B-BlueStar-v3-Derestricted`
- `Qwen3.5-27B-BlueStar-v3-Derestricted-Lite`
- `Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled-Derestricted`
- `Qwen3.5-27B-Claude-4.6-Opus-Reasoning-Distilled-Derestricted-Lite`
- `Qwen3.5-27B-Dark-Nexus-v3.0-Derestricted`
- `Qwen3.5-27B-Dark-Nexus-v3.0-Derestricted-Lite`
- `Qwen3.5-27B-Derestricted`
- `Qwen3.5-27B-Infracelestial`
- `Qwen3.5-27B-Marvin-DPO-V2-Derestricted`
- `Qwen3.5-27B-Marvin-DPO-V2-Derestricted-Lite`
- `Qwen3.5-27B-Marvin-V2-Derestricted`
- `Qwen3.5-27B-Marvin-V2-Derestricted-Lite`
- `Qwen3.5-27B-Musica-v1`
- `Qwen3.5-27B-NaNovel-Derestricted`
- `Qwen3.5-27B-NaNovel-Derestricted-Lite`
- `Qwen3.5-27B-Omega-Evolution-v2.0-Derestricted`
- `Qwen3.5-27B-Omega-Evolution-v2.0-Derestricted-Lite`
- `Qwen3.5-27B-Omega-Evolution-v2.2-Derestricted`
- `Qwen3.5-27B-Omega-Evolution-v2.2-Derestricted-Lite`
- `Qwen3.5-27B-Omnimerge-v2-Derestricted`
- `Qwen3.5-27B-Omnimerge-v2-Derestricted-Lite`
- `Qwen3.5-27B-Queen-Derestricted`
- `Qwen3.5-27B-Queen-Derestricted-Lite`
- `Qwen3.5-27B-QuettaLLMs-Koreasoner-V3-Derestricted`
- `Qwen3.5-27B-QuettaLLMs-Koreasoner-V3-Derestricted-Lite`
- `Qwen3.5-27B-RpRMax-v1`
- `Qwen3.5-27B-Vivid-Durian`
- `Qwen3.5-27B-Writer-Derestricted`
- `Qwen3.5-27B-Writer-Derestricted-Lite`
- `Qwen3.5-27B-Writer-V2-Derestricted`
- `Qwen3.5-27B-Writer-V2-Derestricted-Lite`
- `Qwen3.5-27B-earica-Derestricted`
- `Qwen3.5-27B-earica-Derestricted-Lite`

### gemini (39)

- `antigravity-preview-05-2026`
- `deep-research-max-preview-04-2026`
- `deep-research-preview-04-2026`
- `deep-research-pro-preview-12-2025`
- `gemini-2.0-flash`
- `gemini-2.0-flash-001`
- `gemini-2.0-flash-lite`
- `gemini-2.0-flash-lite-001`
- `gemini-2.5-computer-use-preview-10-2025`
- `gemini-2.5-flash`
- `gemini-2.5-flash-image`
- `gemini-2.5-flash-lite`
- `gemini-2.5-flash-preview-tts`
- `gemini-2.5-pro`
- `gemini-2.5-pro-preview-tts`
- `gemini-3-flash-preview`
- `gemini-3-pro-image`
- `gemini-3-pro-image-preview`
- `gemini-3-pro-preview`
- `gemini-3.1-flash-image`
- `gemini-3.1-flash-image-preview`
- `gemini-3.1-flash-lite`
- `gemini-3.1-flash-lite-image`
- `gemini-3.1-flash-lite-preview`
- `gemini-3.1-flash-tts-preview`
- `gemini-3.1-pro-preview`
- `gemini-3.1-pro-preview-customtools`
- `gemini-3.5-flash`
- `gemini-flash-latest`
- `gemini-flash-lite-latest`
- `gemini-omni-flash-preview`
- `gemini-pro-latest`
- `gemini-robotics-er-1.5-preview`
- `gemini-robotics-er-1.6-preview`
- `gemma-4-26b-a4b-it`
- `gemma-4-31b-it`
- `lyria-3-clip-preview`
- `lyria-3-pro-preview`
- `nano-banana-pro-preview`

### grok (10)

- `grok-4.20-0309-non-reasoning`
- `grok-4.20-0309-reasoning`
- `grok-4.20-multi-agent-0309`
- `grok-4.3`
- `grok-4.5`
- `grok-build-0.1`
- `grok-imagine-image`
- `grok-imagine-image-quality`
- `grok-imagine-video`
- `grok-imagine-video-1.5`

### ollama

Use this provider's standard model names (routed by the prefixes above).

### openai

Use this provider's standard model names (routed by the prefixes above).

## Examples

OpenAI dialect (curl):

```sh
curl https://cerber.ihatebot.com/v1/chat/completions \
  -H 'Authorization: Bearer $KEY' -H 'Content-Type: application/json' \
  -d '{"model":"claude-sonnet-5","messages":[{"role":"user","content":"hi"}]}'
```

Anthropic dialect (curl):

```sh
curl https://cerber.ihatebot.com/v1/messages \
  -H 'Authorization: Bearer $KEY' -H 'anthropic-version: 2023-06-01' -H 'Content-Type: application/json' \
  -d '{"model":"claude-sonnet-5","max_tokens":256,"messages":[{"role":"user","content":"hi"}]}'
```

OpenAI Python SDK:

```python
from openai import OpenAI
client = OpenAI(base_url="https://cerber.ihatebot.com/v1", api_key="$KEY")
client.chat.completions.create(model="claude-sonnet-5", messages=[{"role":"user","content":"hi"}])
```

Streaming is supported on both endpoints (`"stream": true`).