文档

把 CheapAI 接入您的工具所需的一切：常用智能体的配置指南、API 参考、常见问题。

Base URL

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

默认（经 CDN）

https://cheapai.io/v1

直连（不经 CDN）

https://api.cheapai.io/v1

如果请求在输出第一个 token 之前可能长时间静默（大提示词下的推理模型、智能体任务），请使用直连地址。CDN 会切断约两分钟没有任何字节的连接，客户端会收到 524，即使回答其实已经在生成中。直连地址没有这个限制，在 CDN 本身无法访问的网络中也能用。其他情况下默认地址更好：路由更快，并有攻击防护。

Claude Code 是 /v1 规则的唯一例外：它会自己拼接路径，所以要填不带后缀的 https://api.cheapai.io（或 https://cheapai.io）。

认证

每个发往 /v1/* 的请求都必须带上 Bearer token（OpenAI 兼容接口）或 x-api-key 请求头（Anthropic 接口）。两者用的是同一个密钥，也就是“密钥”页面中以 sk- 开头的字符串。

bash

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

# Anthropic 风格
x-api-key: sk-...

POST/v1/chat/completions

兼容 OpenAI 的 Chat Completions。适用于目录中的所有模型（Claude、GPT、Gemini 等）。设置 stream: true 即为流式输出。

bash

curl https://cheapai.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_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_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/messages

Anthropic 原生 Messages API。调用 Claude 模型需要扩展思考、原生 tool_use 块、提示词缓存或任何 Claude 专属参数时使用。

bash

curl https://cheapai.io/v1/messages \
  -H "x-api-key: YOUR_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_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 YOUR_API_KEY"

POST/v1/images/generations

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

bash

curl https://cheapai.io/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "a lighthouse at dusk, long exposure",
    "n": 1
  }'

根据模型不同，响应为 {"data":[{"url":…}]} 或 b64_json。部分 SDK 附带的额外参数（size、quality、style）会被接受并忽略。

仅支持文生图。grok-imagine 会完全忽略输入的图片：它不会编辑或改变您发送的图片风格，而是根据提示词生成新图。要编辑已有图片，请通过 /v1/chat/completions 调用 gemini-3.1-flash-image-preview，并把图片作为多模态消息的一部分发送，它会保留原图内容。不支持 /v1/images/edits。

POST/v1beta/models/{model}:generateContent

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

bash

curl https://cheapai.io/v1beta/models/gemini-3.1-pro-high:generateContent \
  -H "x-goog-api-key: YOUR_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/dashboard/billing/subscription

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

bash

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

# 已消费，单位为美分
curl https://cheapai.io/v1/dashboard/billing/usage \
  -H "Authorization: Bearer YOUR_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	上游故障，请求会自动在备用线路上重试。

超时与流式输出

唯一的硬性限制是模型开始回答之前可以静默多久，约 90 秒。保活 ping 对此无效：它只在服务商开始响应之后才发送。我们前面的 Cloudflare 基于同样的原因在约 125 秒时断开，所以您最先碰到的是网关的限制。

请发送 stream: true，这样长回答不会被截断。token 一旦开始输出，超时就不再生效；回答中途出现停顿时，网关每 60 秒发送一次保活 ping，即使模型在回答中途沉默一阵，连接也不会断开。十分钟的生成也能顺利完成。

也请调大您自己客户端的超时：很多 SDK 默认 30–60 秒，比我们的还严格。Claude Code 相关的变量是 API_TIMEOUT_MS 和 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS。

长时间静默通常是推理模型造成的：它们先思考，再输出内容。如果某个模型经常碰到上限，换用同系列中更轻量的模型，通常会快得多开始回答。