Quick start

Base URL & authentication

These URLs are generated from the host and install path serving this page, so they work unchanged on any host, sub-folder, port or HTTPS setup this application is installed under. Hosts are validated against the operator's allowlist; on an unrecognised host they fall back to localhost.

Why two URLs? OpenAI SDKs treat the base URL as a prefix for /chat/completions, so it includes /v1. Claude Code and the official Anthropic SDK append /v1/messages to the base URL themselves, so their base URL must not include /v1. AI SDK's @ai-sdk/anthropic (used by OpenCode) appends only /messages, so its baseURL does include /v1 — see Connect OpenCode.

Authentication

Every endpoint accepts your key as Authorization: Bearer YOUR_API_KEY. Anthropic-style clients may instead send x-api-key: YOUR_API_KEY — both are accepted on every endpoint.

Environment variables

Connect Claude Code

CheapaAPI exposes an Anthropic Messages-compatible endpoint for Claude Code. Use the base URL without /v1: https://cheapaapi.com — Claude Code adds the Messages path itself.

Temporary setup session only

Persistent setup

On Windows, save the variables for your user account, then open a new terminal:

On macOS or Linux, add the three export lines to ~/.zshrc or ~/.bashrc, then open a new terminal.

Start Claude Code

• ANTHROPIC_MODEL is optional — replace claude-opus-5.5 with any Model ID from the Available models list, or leave it unset and pick models inside Claude Code.
• ANTHROPIC_API_KEY also works on this gateway — it sends the same key via the x-api-key header.
• This gateway accepts every enabled model over the Messages endpoint, including OpenAI-compatible ones — the request is converted automatically.
• Claude Code's pre-flight count_tokens calls are answered locally — no upstream request, no charge (see POST /v1/messages/count_tokens).
• Verify the connection with /status inside the REPL.

Troubleshooting: 401 → wrong key · 404 / model not found → the ANTHROPIC_MODEL ID is not in your catalog · connection refused → wrong base URL (must be the root, without /v1).

Connect Codex CLI

CheapaAPI supports the Responses API used by Codex CLI. A separate profile keeps your normal Codex settings unchanged.

Create a profile persistent

Edit (or create) your Codex config file and add the profile below:

• macOS / Linux: ~/.codex/config.toml
• Windows: %USERPROFILE%\.codex\config.toml

If your config.toml already defines model / model_provider at the top, leave them as they are — the profile only overrides them when you start Codex with --profile.

Set your API key

Start Codex

To use another CheapaAPI model for one session:

• The profile calls POST https://cheapaapi.com/v1/responses — see POST /v1/responses for current compatibility.
• env_key is just a name — it must match the environment variable you set. Keep the key out of the TOML file itself.
• Verify inside Codex with /status — it shows the active provider, base URL and model.

Connect OpenCode

OpenCode uses two CheapaAPI provider adapters. GPT, Grok and other OpenAI-compatible models use @ai-sdk/openai-compatible. Claude-protocol models must use @ai-sdk/anthropic so OpenCode calls CheapaAPI's Anthropic Messages endpoint.

Create the config persistent

Open or create:

• macOS / Linux: ~/.config/opencode/opencode.jsonc
• Windows: %USERPROFILE%\.config\opencode\opencode.jsonc
• Project-level alternative: an opencode.jsonc in the project root

You can replace or extend the lists with IDs from the Available models section below. Keep Claude-protocol models under cheapaapi-anthropic — putting them under the OpenAI-compatible provider produces a Messages endpoint error.

Add your API key

Start OpenCode

For Claude-protocol models:

You can also run /models inside OpenCode and select a configured CheapaAPI model.

GET /v1/models

List the models enabled on this gateway with their context capacity, supported parameters and per-1M-token pricing. Requires a valid API key. Clients use the response to size requests before sending them. Listing still works while an account is awaiting email verification, so pre-configured clients can enumerate models before their first generation call.

type and display_name mirror Anthropic's model-list fields (Claude clients read them); context_length, max_output_tokens, supported_parameters and pricing are OpenRouter-style extras. OpenAI SDKs ignore all of them. supported_parameters is null when the model accepts every parameter, max_output_tokens is null when unbounded, and pricing.long_context is present only when the operator configured a long-context tier.

POST /v1/chat/completions

OpenAI Chat Completions format — streaming and non-streaming. Only n=1 is supported; system/developer, user, assistant and tool roles are accepted.

The response is a standard OpenAI chat.completion object including usage with prompt_tokens_details.cached_tokens and completion_tokens_details.reasoning_tokens (reported as 0 when the upstream does not provide them).

Streaming (SSE)

Set "stream": true. Chunks are forwarded to you incrementally as the upstream provider generates them — nothing is buffered server-side. The stream ends with a usage chunk and data: [DONE] — usage is always sent, so stream_options.include_usage is not required. The request ID is returned in the X-Request-Id response header.

Python example

POST /v1/responses

OpenAI Responses API format (including streaming events like response.output_text.delta). Accepts input as a string or an array of message/function-call items. Top-level instructions is honored as the system prompt. Text and image parts are supported; audio input is not accepted here.

POST /v1/messages

Anthropic Messages format for Claude-style clients and agents. Requires max_tokens (1–200000). Authentication uses the same key via x-api-key (sent automatically by Anthropic SDKs) or the standard Bearer header. system, tool_use/tool_result blocks and thinking are supported.

Remember: raw curl uses the full path above, but Claude Code and Anthropic SDKs want the base URL without /v1 — see Connect Claude Code.

POST /v1/messages/count_tokens

Anthropic-compatible token counting, used by Claude Code to size a conversation before sending it. The count is estimated by the gateway — no upstream request is made, nothing is billed and no rate-limit quota is used. The body takes the same model and messages shapes as POST /v1/messages; max_tokens is not required.

The count covers the messages plus any tools definitions and ignores max_tokens, so it matches the gateway's own prompt estimate.

Tool / function calling

Send standard OpenAI tools definitions to any model with the tool_calling capability. Tool call deltas are streamed in OpenAI format (tool_calls in delta) and completed tool calls are returned in the message body for non-streaming requests. Anthropic-style tool_use/tool_result blocks are converted automatically on /v1/messages.

Direct Web Search API & Live Chat Grounding

You can use real-time web search in two ways: (1) Live Web Grounding inside Chat / LLM requests, or (2) Direct Web Search API (POST /v1/web/search) to retrieve structured web search results or sourced answers directly.

1. Live Web Search in Chat / Responses / Messages

Enable live web search on any supported model by appending :online (or :online/linkup-deep for deep research) to the model ID, or by passing "web_search": true in the request body:

Also accepts "web_search": true, "web_search_options": {"search_context_size": "medium"}, OpenRouter-style "plugins": [{"id": "web"}], OpenAI Responses "tools": [{"type": "web_search_preview"}], and Anthropic "tools": [{"type": "web_search_20250305", "name": "web_search"}]. Billing combines the model's token usage plus the per-search fee.

2. Direct Web Search API — POST /v1/web/search

Execute a standalone web search without calling a chat model. Supports depth ("standard" or "deep"), output_type ("searchResults" or "sourcedAnswer"), max_results (1–20), include_domains, exclude_domains, from_date, and to_date.

Images (vision) & audio input

Models with vision accept image input on every protocol. The gateway validates images before forwarding — unsupported input types, malformed images or oversized payloads return a clean 400 without consuming credits.

OpenAI Chat Completions

A base64 data URL works in the same slot: {"type":"image_url","image_url":{"url":"data:image/png;base64,…"}}

OpenAI Responses

Anthropic Messages

Audio input

Models whose Inputs include audio accept inline audio on Chat Completions (check the Available models table — most text/vision models do not). Send a base64 payload (no data: prefix) plus its container format:

Audio is forwarded only to OpenAI-compatible Chat Completions upstreams. /v1/responses does not accept input_audio, and Anthropic-protocol upstreams reject it with 400 unsupported_input — pick a chat-completions channel for audio models. Images, by contrast, are converted for every upstream protocol.

Billing

Images are billed as input tokens — exactly how OpenAI, Anthropic and Google charge for vision. The provider converts each image into input tokens (OpenAI: 512px tiles at 170 tokens each + 85 base; Anthropic ≈ width × height ÷ 750; Gemini: flat ~258) and reports them inside prompt_tokens / input_tokens in the usage. Your account is charged at the model's normal input price for those tokens — no separate image fee. Audio works the same way: it is billed as provider-reported input tokens with no separate fee (pre-authorization estimates each audio clip at roughly 1,600 tokens).

Reasoning models

For models with the reasoning capability the gateway applies a default thinking effort of low automatically — small tasks stay fast and cheap. Any reasoning parameter you send yourself always wins over the default, and the default is skipped when the model's parameter policy does not allow reasoning parameters.

• Chat Completions: "reasoning_effort": "low" | "medium" | "high" (none, minimal and xhigh are also accepted and forwarded where the upstream supports them). OpenRouter-style "reasoning": {"effort": "..."} is accepted too.
• Responses: "reasoning": {"effort": "low"}.
• Anthropic Messages: send "thinking": {"type": "enabled", "budget_tokens": 2048} directly, or just "reasoning_effort": "low" and the gateway maps it to a thinking budget (low → 2048, medium → 8192, high → 16384, xhigh → 32768) that is always kept below your max_tokens. While thinking is enabled, temperature/top_p are dropped (Anthropic rejects them).

Reasoning deltas stream as reasoning_content (chat), reasoning summary items (responses) or thinking blocks (messages), and reasoning tokens are included in usage when the provider reports them.

Context limits & long-context pricing

Each model advertises its real capacity via GET /v1/models (context_length, max_output_tokens). How oversized requests are handled:

• If the input alone fills the model's context window, the request is rejected up front with 400 context_length_exceeded (OpenAI wording) or prompt is too long (Anthropic wording on /v1/messages) — no credits are consumed. Coding agents treat these codes as a signal to compact their context.
• If the requested max_tokens exceeds the model's maximum output or the remaining context room, it is capped (not rejected). The response's usage always reflects the tokens actually processed.
• The token counts we validate are close estimates; if a request still overflows at the provider, the provider's own error is passed back (as an error event on streaming requests) and you are not charged.

Long-context (tiered) pricing

Some providers charge higher per-token rates once a request's input crosses a threshold (e.g. GPT-4.1 above 272K input tokens, Gemini 2.5 Pro above 200K). When an operator configures a threshold for a model, requests whose total input tokens exceed it are billed at the long-context rates, shown in pricing.long_context on GET /v1/models and in your dashboard pricing. Pre-authorization holds use the same tier, so the estimate matches the final charge.

Errors

Errors use OpenAI-compatible JSON (Anthropic shape on /v1/messages) with proper HTTP status codes:

Rate limits & billing

Each request is pre-authorized against your credit balance (a hold equal to the estimated cost), then settled with the actual token usage when the response completes. Failed requests are never charged — holds are released automatically. Responses carry an X-Request-Id header you can quote in support requests (every endpoint except a successful GET /v1/models); the same ID appears in your usage history. Request bodies are capped by the operator (max_request_mb, default 4 MB) and larger bodies return 413 before any processing.

Per-key (default 60 req/min) and per-account (default 120 req/min) rate limits apply — a value of 0 means unlimited — along with optional daily/monthly spend caps, all as configured by the operator. The same limits cover the dashboard chat as well as the API.

Available models