CheapAI API 参考
查看 CheapAI 的基础地址、认证方式、OpenAI、Anthropic 和 Gemini 接口,以及流式响应和余额查询。
选择 API 接口
请查看模型目录,确认所选模型支持的接口格式。 模型目录
| 客户端 | 基础地址 | 请求路径 | 认证方式 |
|---|---|---|---|
| OpenAI SDK | https://cheapai.io/v1 | /v1/chat/completions | Authorization: Bearer |
| Codex | https://cheapai.io/v1 | /v1/responses | Authorization: Bearer |
| Claude Code 和 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
有两个地址,区别只有一点:前面是否经过 CDN。其他一切(密钥、模型、价格、请求格式)完全相同。
524 时,可以尝试直连地址以避开 CDN 超时。网关和客户端的超时仍然有效。切换地址时,请参照表格中的基础地址,仅替换域名。Claude Code、Anthropic SDK 和 Gemini SDK 使用不带 /v1 后缀的地址。
认证
同一个 CheapAI 密钥可用于所有支持的协议。请根据接口选择表格中的认证请求头。
# OpenAI 风格
Authorization: Bearer sk-...
# Anthropic 风格
x-api-key: sk-.../v1/chat/completionsChat Completions 适用于支持 OpenAI 兼容格式的对话模型。设置 stream: true 可以启用流式响应。
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);响应格式
{
"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 使用此接口。请选择支持 Responses 的模型,在 input 字段中传入文本,并通过 stream: true 接收事件流。
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 原生 Messages API。调用 Claude 模型需要扩展思考、原生 tool_use 块、提示词缓存或任何 Claude 专属参数时使用。
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);响应格式
{
"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/models列出您的密钥可用的模型(OpenAI 风格的返回格式)。
curl https://cheapai.io/v1/models \
-H "Authorization: Bearer $CHEAPAI_API_KEY"/v1/images/generations图像生成。按次计费,不按 token 计费,价格见模型页面。
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 接收多模态消息中的图片。
/v1beta/models/{model}:generateContentGemini 原生 API。使用 google_search 联网搜索时必须走这里,OpenAI 兼容路径没有对应功能。
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 块,列出信息来源。
/v1/balance一次请求查询 API 密钥的余额:钱包、订阅以及该密钥还能消费的金额。
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"
# }/v1/dashboard/billing/subscription余额与消费,采用 OpenAI 兼容格式,现有工具无需修改即可读取。
# 总额度(余额 + 已消费),美元
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流式输出
在请求体中传入 "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 | 上游故障,网关可能通过备用线路重试。 |
超时与流式输出
等待响应开始时,客户端和网关有各自的超时限制。较长的请求可在支持 SSE 的接口上使用 "stream": true。流式响应有独立的空闲超时。保活 ping 用于维持连接,文本、推理和工具调用事件表示生成进度。