CheapAI
RU EN 中文

CheapAI API 参考

查看 CheapAI 的基础地址、认证方式、OpenAI、Anthropic 和 Gemini 接口,以及流式响应和余额查询。

选择 API 接口

请查看模型目录,确认所选模型支持的接口格式。 模型目录

客户端基础地址请求路径认证方式
OpenAI SDKhttps://cheapai.io/v1/v1/chat/completionsAuthorization: Bearer
Codexhttps://cheapai.io/v1/v1/responsesAuthorization: Bearer
Claude Code 和 Anthropic SDKhttps://cheapai.io/v1/messagesx-api-key
Google Gemini SDKhttps://cheapai.io/v1beta/models/{model}:generateContentx-goog-api-key

Base URL

有两个地址,区别只有一点:前面是否经过 CDN。其他一切(密钥、模型、价格、请求格式)完全相同。

默认(经 CDN)
https://cheapai.io/v1
直连(不经 CDN)
https://api.cheapai.io/v1
遇到 CDN 返回的 HTTP 524 时,可以尝试直连地址以避开 CDN 超时。网关和客户端的超时仍然有效。

切换地址时,请参照表格中的基础地址,仅替换域名。Claude Code、Anthropic SDK 和 Gemini SDK 使用不带 /v1 后缀的地址。

认证

同一个 CheapAI 密钥可用于所有支持的协议。请根据接口选择表格中的认证请求头。

bash
# OpenAI 风格
Authorization: Bearer sk-...

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

Chat Completions 适用于支持 OpenAI 兼容格式的对话模型。设置 stream: true 可以启用流式响应。

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);
响应格式
{
  "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 使用此接口。请选择支持 Responses 的模型,在 input 字段中传入文本,并通过 stream: true 接收事件流。

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 原生 Messages API。调用 Claude 模型需要扩展思考、原生 tool_use 块、提示词缓存或任何 Claude 专属参数时使用。

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);
响应格式
{
  "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

列出您的密钥可用的模型(OpenAI 风格的返回格式)。

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

图像生成。按次计费,不按 token 计费,价格见模型页面。

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
  }'

此示例根据文本生成图片。发送图片前,请查看模型支持哪些输入。Gemini Flash Image 可通过 /v1/chat/completions 接收多模态消息中的图片。

POST/v1beta/models/{model}:generateContent

Gemini 原生 API。使用 google_search 联网搜索时必须走这里,OpenAI 兼容路径没有对应功能。

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": {}}]
  }'

这里按 Google SDK 的习惯,用 x-goog-api-key 认证,密钥与其他地方相同。流式输出请用 :streamGenerateContent。联网搜索的回答会附带 groundingMetadata 块,列出信息来源。

一旦把工具转换成 OpenAI 的 function_declarations,联网搜索就会失效,这正是单独提供这个接口的原因。如果只需要对话,用 /v1/chat/completions 调用 Gemini 模型完全没问题。
GET/v1/balance

一次请求查询 API 密钥的余额:钱包、订阅以及该密钥还能消费的金额。

bash
curl https://cheapai.io/v1/balance \
  -H "Authorization: Bearer $CHEAPAI_API_KEY"
# → {
#   "available_usd": 166.52,   // 该密钥还能消费的金额
#   "balance_usd": 12.34,      // 钱包余额
#   "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"
# }
不限额的密钥显示整个账户(scope: account)。限额密钥只显示自己的额度和剩余(scope: key),无法看到账户余额。密钥只能放在请求头中;每个密钥每分钟最多 60 次请求。
GET/v1/dashboard/billing/subscription

余额与消费,采用 OpenAI 兼容格式,现有工具无需修改即可读取。

bash
# 总额度(余额 + 已消费),美元
curl https://cheapai.io/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer $CHEAPAI_API_KEY"
# → {"hard_limit_usd": 148.51, "access_until": 0, …}

# 已消费,单位为美分
curl https://cheapai.io/v1/dashboard/billing/usage \
  -H "Authorization: Bearer $CHEAPAI_API_KEY"
# → {"total_usage": 7639.53}   // = $76.40
hard_limit_usd 不是剩余余额,而是余额加上已消费的金额,沿用了 OpenAI 该字段的语义。剩余余额 = hard_limit_usd − total_usage / 100。以上例为例:148.51 − 76.40 = $72.11。 剩余金额包含订阅额度;限额密钥按密钥本身统计。

流式输出

在请求体中传入 "stream": true,响应就是服务器推送事件流(SSE)。/v1/chat/completions 使用 OpenAI SSE 格式(data: {…} 数据块,以 data: [DONE] 结束)。/v1/messages 使用 Anthropic SSE 格式(类型化事件:message_start、content_block_delta、message_stop)。

错误

错误格式与上游厂商一致,HTTP 状态码反映错误类别。

HTTP含义
400请求有误:模型名称、参数或格式不正确。
401缺少 API 密钥或密钥无效。
402余额不足,充值后即可继续。
429被上游厂商限流。
5xx上游故障,网关可能通过备用线路重试。

排查 429、503 和流式响应中断

超时与流式输出

等待响应开始时,客户端和网关有各自的超时限制。较长的请求可在支持 SSE 的接口上使用 "stream": true。流式响应有独立的空闲超时。保活 ping 用于维持连接,文本、推理和工具调用事件表示生成进度。