CheapAI API reference
Find CheapAI base URLs, authentication, OpenAI, Anthropic and Gemini endpoints, streaming formats and balance checks.
Choose an API
Check the model catalog for supported API formats. Model catalog
| Client | Base URL | Route | Authentication |
|---|---|---|---|
| OpenAI SDK | https://cheapai.io/v1 | /v1/chat/completions | Authorization: Bearer |
| Codex | https://cheapai.io/v1 | /v1/responses | Authorization: Bearer |
| Claude Code and Anthropic SDK | https://cheapai.io | /v1/messages | x-api-key |
| Google Gemini SDK | https://cheapai.io | /v1beta/models/{model}:generateContent | x-goog-api-key |
Base URL
There are two addresses, and they differ in one thing: whether a CDN sits in front. Everything else — keys, models, prices, request format — is identical.
524, try the direct address to bypass the CDN timeout. Gateway and client timeouts still apply.To switch hosts, use the base URL from the table and replace its domain. Claude Code, the Anthropic SDK and the Gemini SDK use the host without a /v1 suffix.
Authentication
Use the same CheapAI key across supported protocols. Choose the authentication header from the table for your endpoint.
# OpenAI-style
Authorization: Bearer sk-...
# Anthropic-style
x-api-key: sk-.../v1/chat/completionsChat Completions is available for chat models that support the OpenAI format. Set stream: true for streaming.
curl https://cheapai.io/v1/chat/completions \
-H "Authorization: Bearer $CHEAPAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"messages": [
{"role": "user", "content": "Hi!"}
]
}'import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.CHEAPAI_API_KEY,
baseURL: "https://cheapai.io/v1",
});
const res = await client.chat.completions.create({
model: "claude-sonnet-4-6",
messages: [{ role: "user", content: "Hi!" }],
});
console.log(res.choices[0].message);Response shape
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "claude-sonnet-4-6",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "..." },
"finish_reason": "stop"
}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 42,
"total_tokens": 52
}
}/v1/responsesCodex uses this interface. Choose a model that supports Responses. Send text in the input field and set stream: true to receive a stream of events.
curl https://cheapai.io/v1/responses \
-H "Authorization: Bearer $CHEAPAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"grok-4.5","input":"Reply with OK."}'/v1/messagesAnthropic-native Messages API. Use for Claude models when you need extended thinking, native tool_use blocks, prompt caching or any Claude-specific param.
curl https://cheapai.io/v1/messages \
-H "x-api-key: $CHEAPAI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi!"}
]
}'import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.CHEAPAI_API_KEY,
baseURL: "https://cheapai.io",
});
const res = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [{ role: "user", content: "Hi!" }],
});
console.log(res.content);Response shape
{
"id": "msg_...",
"type": "message",
"role": "assistant",
"content": [{ "type": "text", "text": "..." }],
"model": "claude-sonnet-4-6",
"stop_reason": "end_turn",
"usage": {
"input_tokens": 10,
"output_tokens": 42,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
}
}/v1/modelsList models available under your key (OpenAI-style envelope).
curl https://cheapai.io/v1/models \
-H "Authorization: Bearer $CHEAPAI_API_KEY"/v1/images/generationsImage generation. Billed per call, not per token — the price is on the models page.
curl https://cheapai.io/v1/images/generations \
-H "Authorization: Bearer $CHEAPAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5",
"prompt": "a lighthouse at dusk, long exposure",
"n": 1
}'This example generates an image from text. Check the model’s supported inputs before sending an image. For example, Gemini Flash Image accepts an image in a multimodal message through /v1/chat/completions.
/v1beta/models/{model}:generateContentNative Gemini API. Needed for google_search grounding — the OpenAI-compatible path has no equivalent.
curl https://cheapai.io/v1beta/models/gemini-3.1-pro-preview:generateContent \
-H "x-goog-api-key: $CHEAPAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "What changed in the news today?"}]}],
"tools": [{"google_search": {}}]
}'Authentication here uses x-goog-api-key, as Google SDKs expect — the same key as everywhere else. Streaming is :streamGenerateContent. Grounded answers come back with a groundingMetadata block listing the sources.
/v1/balanceRemaining balance for an API key in one call: wallet, subscription, and how much this key can still spend.
curl https://cheapai.io/v1/balance \
-H "Authorization: Bearer $CHEAPAI_API_KEY"
# → {
# "available_usd": 166.52, // how much this key can still spend
# "balance_usd": 12.34, // wallet
# "subscription": {"plan": "Pro", "remaining_usd": 154.18, "total_usd": 157.61, "expires_at": "2026-12-14T11:24:16Z"},
# "used_usd": 34.43,
# "key": {"name": "my-key", "unlimited": true, "used_usd": 3.21, "limit_usd": null, "remaining_usd": null, "expires_at": null},
# "scope": "account", "currency": "USD"
# }/v1/dashboard/billing/subscriptionBalance and spend, in the OpenAI-compatible shape — so existing tooling reads it without changes.
# total available (remaining + already spent), USD
curl https://cheapai.io/v1/dashboard/billing/subscription \
-H "Authorization: Bearer $CHEAPAI_API_KEY"
# → {"hard_limit_usd": 148.51, "access_until": 0, …}
# spent, in hundredths of a dollar
curl https://cheapai.io/v1/dashboard/billing/usage \
-H "Authorization: Bearer $CHEAPAI_API_KEY"
# → {"total_usage": 7639.53} // = $76.40Streaming
Pass "stream": true in the body and the response is a server-sent-event stream. For /v1/chat/completions the format is OpenAI SSE (data: {…} chunks terminated by data: [DONE]). For /v1/messages the format is Anthropic SSE (typed events: message_start, content_block_delta, message_stop).
Errors
Errors follow the upstream provider format. HTTP status reflects the failure class.
| HTTP | Meaning |
|---|---|
| 400 | Bad request — model name, params, schema. |
| 401 | Missing or invalid API key. |
| 402 | Balance is insufficient — top up to continue. |
| 429 | Rate-limited by the upstream provider. |
| 5xx | Upstream outage — the gateway can retry using a fallback channel. |
Timeouts and streaming
Client and gateway timeouts apply while waiting for the response to begin. For long requests, use "stream": true on endpoints that support SSE. Streams have their own idle limits. A keepalive ping keeps the connection alive. Text, reasoning and tool-call events show generation progress.