CheapAI

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

ClientBase URLRouteAuthentication
OpenAI SDKhttps://cheapai.io/v1/v1/chat/completionsAuthorization: Bearer
Codexhttps://cheapai.io/v1/v1/responsesAuthorization: Bearer
Claude Code and Anthropic SDKhttps://cheapai.io/v1/messagesx-api-key
Google Gemini SDKhttps://cheapai.io/v1beta/models/{model}:generateContentx-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.

Default — behind a CDN
https://cheapai.io/v1
Direct — no CDN
https://api.cheapai.io/v1
If the CDN returns HTTP 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.

bash
# OpenAI-style
Authorization: Bearer sk-...

# Anthropic-style
x-api-key: sk-...
POST/v1/chat/completions

Chat Completions is available for chat models that support the OpenAI format. Set stream: true for streaming.

bash
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!"}
    ]
  }'
javascript
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
  }
}
POST/v1/responses

Codex 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.

bash
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."}'
POST/v1/messages

Anthropic-native Messages API. Use for Claude models when you need extended thinking, native tool_use blocks, prompt caching or any Claude-specific param.

bash
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!"}
    ]
  }'
javascript
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
  }
}
GET/v1/models

List models available under your key (OpenAI-style envelope).

bash
curl https://cheapai.io/v1/models \
  -H "Authorization: Bearer $CHEAPAI_API_KEY"
POST/v1/images/generations

Image generation. Billed per call, not per token — the price is on the models page.

bash
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.

POST/v1beta/models/{model}:generateContent

Native Gemini API. Needed for google_search grounding — the OpenAI-compatible path has no equivalent.

bash
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.

Convert the tool to OpenAI function_declarations and grounding falls off — that is why this endpoint exists separately. If you only need chat, /v1/chat/completions handles Gemini models fine.
GET/v1/balance

Remaining balance for an API key in one call: wallet, subscription, and how much this key can still spend.

bash
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"
# }
A key without a limit shows the whole account (scope: account). A key with a limit shows only its own limit and remainder (scope: key) — the account balance is not visible through it. The key is accepted in a header only; up to 60 requests per minute per key.
GET/v1/dashboard/billing/subscription

Balance and spend, in the OpenAI-compatible shape — so existing tooling reads it without changes.

bash
# 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.40
hard_limit_usd is NOT your remaining balance — it is remaining plus already spent, inherited from the OpenAI field semantics. The remaining balance is hard_limit_usd − total_usage / 100. In the example above: 148.51 − 76.40 = $72.11. The remainder includes subscription quota; for a key with a limit the numbers are per key.

Streaming

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.

HTTPMeaning
400Bad request — model name, params, schema.
401Missing or invalid API key.
402Balance is insufficient — top up to continue.
429Rate-limited by the upstream provider.
5xxUpstream outage — the gateway can retry using a fallback channel.

Troubleshoot 429s, 503s and interrupted streams

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.