开发文档

KaKa API 是一个 OpenAI / Anthropic 双兼容网关, 31 个主流模型 + 13 个分组倍率, 现有客户端无需改业务代码, 换 base_url + api_key 即可调用。

开始使用

欢迎使用 KaKa API。在开始之前, 我们建议您先花两分钟浏览以下几个章节, 它们会帮助你理解如何把 KaKa API 接入你的应用。

👉 快速开始 — 5 分钟内发起第一次调用
👉 OpenAI 兼容接口 — 适合绝大多数 OpenAI 系客户端
👉 Anthropic 兼容接口 — 适合 Claude Code / Cursor / Cline
👉 计费与用量 — 了解费率、扣费规则和如何看账单

快速开始

把请求地址指向你的网关, 并在请求头带上你的 Key, 下面用三种方式发起一次调用:

# OpenAI 兼容调用
curl -X POST "https://kakaapi.cn/v1/chat/completions" \
  -H "Authorization: Bearer $KK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6",
    "messages": [{"role": "user", "content": "用一句话介绍量子计算"}],
    "stream": false
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://kakaapi.cn/v1",
    api_key="YOUR_API_KEY",
)
resp = client.chat.completions.create(
    model="gpt-5.6",
    messages=[{"role": "user", "content": "用一句话介绍量子计算"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://kakaapi.cn/v1",
  apiKey: "YOUR_API_KEY",
});
const resp = await client.chat.completions.create({
  model: "gpt-5.6",
  messages: [{ role: "user", content: "用一句话介绍量子计算" }],
});
console.log(resp.choices[0].message.content);

把 https://kakaapi.cn 换成你的网关地址（部署后为你的域名），YOUR_API_KEY 换成控制台生成的 Key。

响应示例（非流式）

{
  "id": "chatcmpl-abc",
  "object": "chat.completion",
  "model": "gpt-5.6",
  "choices": [{
    "message": { "role": "assistant", "content": "量子计算利用叠加与纠缠并行处理信息…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 12, "completion_tokens": 28, "total_tokens": 40 }
}

OpenAI 兼容接口

KaKa API 完全兼容 /v1/chat/completions、/v1/completions、/v1/embeddings、/v1/models 四个 OpenAI 端点, 任何支持 base_url 的 OpenAI 客户端均可直接使用：

官方：openai SDK、openai-node
LLM 框架：LangChain、LlamaIndex、Semantic Kernel
Agent / 工具：OpenAI Codex、OpenCode、Hermes

流式调用

设置 stream: true 即可拿到 SSE 流式输出：

curl -X POST "https://kakaapi.cn/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6",
    "stream": true,
    "messages": [{"role":"user","content":"写一首七言绝句"}]
  }'

列出可用模型

curl "https://kakaapi.cn/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

返回的 JSON 中 data[].id 即为请求体 model 字段可用的值, 也可以从模型广场直接查看。

Function Calling / Tools

支持 tools 数组, 行为与 OpenAI 保持一致。注意：

不同上游支持的 tool 格式略有差异, 跨模型复用请先验证
当 tool_choice 为 "auto" 时由模型自行决定

Anthropic 兼容接口

KaKa API 同时原生支持 Anthropic Messages API 协议（/v1/messages），你无需任何转换层, Claude Code / Cursor / Cline 等工具可直连。

基础调用

curl -X POST "https://kakaapi.cn/v1/messages" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "讲个冷笑话"}]
  }'

鉴权头我们同时支持 x-api-key（Anthropic 风格）和 Authorization: Bearer（OpenAI 风格），后者兼容性更好, 推荐使用。

流式响应

设置 "stream": true, 网关会按 Anthropic 规范输出 event: ...\ndata: ...\n\n SSE。

系统提示

system 字段支持字符串或数组：

"system": [
  { "type": "text", "text": "你是一个简洁的助手" }
]

生图接入

KaKa API 提供 OpenAI Images API 兼容端点 POST /v1/images/generations。当前可用的生图模型：

模型	说明	价格(¥/张)
`gpt-image-2`	1024×1024 标准出图	¥0.18
`gpt-image-2-4k`	4K 高清出图	¥0.66
`gemini-3-pro-image-preview`	Google 多模态出图	¥0.22
`gemini-3.1-flash-image-preview`	Flash 速出图	¥0.06

调用示例

curl -X POST "https://kakaapi.cn/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "赛博朋克风的太空站",
    "n": 1,
    "size": "1024x1024"
  }'

返回 { "data": [{ "url": "..." }] }, url 有效期 24 小时, 请及时下载。

Codex 与 CC-Switch

Codex 是 OpenAI 官方的 CLI / 编辑器插件, CC-Switch 是社区的 Claude 客户端切换器。两者均通过修改 base_url 和 api_key 走 KaKa 网关。

Codex 配置

编辑 ~/.codex/config.json:

{
  "provider": "openai",
  "base_url": "https://kakaapi.cn/v1",
  "api_key": "YOUR_API_KEY",
  "model": "gpt-5.6"
}

CC-Switch 配置

在 CC-Switch 中「添加 Provider」, Provider 选 OpenAI Compatible, 填入 https://kakaapi.cn/v1 和你的 API Key, 保存即可在 Claude Code 中选用。

OpenCode 配置

OpenCode 是一个多模型 AI 编辑器, 在 opencode.json 中加入 provider：

{
  "providers": [
    {
      "name": "kaka",
      "baseURL": "https://kakaapi.cn/v1",
      "apiKey": "YOUR_API_KEY",
      "models": ["gpt-5.6", "claude-opus-5", "gemini-3-pro-image-preview"]
    }
  ]
}

OpenClaw 配置

OpenClaw 是开源的 Anthropic 协议 CLI, 配置文件 ~/.openclaw/config.yaml:

provider: kaka
base_url: https://kakaapi.cn
api_key: YOUR_API_KEY
default_model: claude-opus-5
models:
  - claude-opus-5
  - claude-sonnet-5
  - claude-haiku-4-5

Hermes 配置

Hermes 是一个轻量级 LLM 代理网关, 在 hermes.yaml 中:

upstreams:
  kaka:
    base_url: "https://kakaapi.cn/v1"
    api_key: "YOUR_API_KEY"
    default_model: "gpt-5.6"

计费与用量

平台会根据实际请求、模型价格和分组倍率记录消费, 最终扣费以站内用量记录为准。

在控制台查看

「仪表盘」展示余额和近期用量概览
「使用记录」展示每次请求的模型、Token、耗时、费用和状态
「API 密钥」可以查看单个密钥的用量, 并设置额度与限流
「我的订单」与「我的订阅」展示充值和套餐状态

通过 API 查询

查询密钥可见的用量信息：

curl "https://kakaapi.cn/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

查询平台扩展的密钥计费信息：

curl "https://kakaapi.cn/v1/sub2api/billing" \
  -H "Authorization: Bearer YOUR_API_KEY"

为什么预估与最终费用可能不同

流式请求通常会提前返回少量 token, 最终费用按 完整使用量 计费
工具调用（Tools）会产生额外的 tool_use 字段计费
生图模型按张数计费, 与 prompt 长度无关
分组倍率是叠加在底价之上, 不同分组倍率不同

错误码

网关与上游错误统一为 JSON: { "error": { "code": "...", "message": "..." } }。

401API Key 无效或缺失 — 检查 Authorization / x-api-key

403跨分组调用被拒绝 — 当前 key 的分组与请求的模型不一致

404模型不存在 — 到模型广场确认可用 model ID

429触发配额或频率限制 — 降低并发或联系扩容

5xx上游或网关异常 — 查看模型状态, 按文档重试

常见问题排查

Q: 调用返回 401, 但 Key 明明是新的？

A: 新创建的 Key 有 30 秒缓存, 等一会儿再试；同时检查是否拼写带上了多余的空格 / 换行；推荐用环境变量而不是硬编码。

Q: 我买的 Pro 分组（×0.35）为什么不能调用 Claude Opus？

A: 每个分组限制了可见模型列表, Pro 分组仅包含 GPT-5.4 / 5.5 / 5.6 等模型, 不包含 Claude 全系。如果要调用 Claude, 请使用「Claude 官方稳定（×1.2）」分组。

Q: 流式响应中途断开怎么办？

A: 网关默认 60 秒无数据则关闭连接, 客户端需要处理 Connection closed 异常并重试, 网关会按已下发的 token 计费, 不会重复扣费。

Q: 余额不足时会怎样？

A: 返回 402 Payment Required, 不再扣费, key 不会被禁用 — 充值后自动恢复。如需限制, 可在「API 密钥」页开启 quota_usd 上限。

Q: 模型延迟突然变高？

A: 进入「控制台 - 我的状态」查看各模型实时 RPM / 响应时间; 切到 Pro / 企业稳定分组能稳定获得更低延迟, 适合生产环境。

⚠️ 不要把你的 API Key 写进前端代码或公开仓库！KaKa API 不会主动索要你的密码 / 余额截图, 谨防钓鱼。