使用指南

项目简介

AIClient2API 是一个突破客户端限制的 API 代理服务，将 Gemini、Antigravity、Qwen Code、Kiro 等原本仅限客户端内使用的免费大模型，转换为可供任何应用调用的标准 OpenAI 兼容接口。

统一接入

通过标准 OpenAI 兼容协议，一次配置即可接入多种大模型

突破限制

利用 OAuth 授权机制，有效突破免费 API 速率和配额限制

协议转换

支持 OpenAI、Claude、Gemini 三大协议间的智能转换

账号池管理

支持多账号轮询、自动故障转移和配置降级

操作流程图

1

配置管理

在「配置管理」页面设置基本参数

  • 设置 API Key
  • 选择启动时初始化的模型提供商
  • 配置高级选项
→
2

生成授权

在「提供商池管理」页面生成 OAuth 授权

方式一：OAuth 授权
  • 点击「生成授权」按钮
  • 在弹窗中完成 OAuth 登录
  • 凭据自动保存
或
方式二：手动上传
  • 新增提供商节点
  • 上传已有的授权文件
  • 手动关联凭据路径
→
3

管理凭据

在「凭据文件管理」页面查看和管理凭据

  • 查看已生成的凭据文件
  • 自动关联到提供商池
  • 删除无效凭据
→
4

开始使用

在「仪表盘」查看路由示例并开始调用 API

  • 查看路由调用示例
  • 复制 API 端点地址
  • 在客户端中配置使用

客户端配置指南

以下是常见 AI 客户端的配置方法，将 API 端点设置为本服务地址即可使用：

Cherry Studio

  1. 打开设置 → 模型服务商
  2. 添加自定义服务商
  3. 设置 API 地址为: http://localhost:3000/{provider}/v1
  4. 填入 API Key（配置文件中的 REQUIRED_API_KEY）

Cline / Continue

  1. 打开 VS Code 设置
  2. 搜索 Cline 或 Continue 配置
  3. 设置 API Base URL 为: http://localhost:3000/{provider}/v1
  4. 填入 API Key 和模型名称

通用 cURL 调用

curl http://localhost:3000/{provider}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "模型名称",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 1000
  }'
提示：将 {provider} 替换为实际的提供商路径，如 gemini-cli-oauth、claude-kiro-oauth 等。可在仪表盘的路由示例中查看完整路径。

Ollama 协议使用

本项目支持 Ollama 协议，可以通过统一接口访问所有支持的模型。

列出所有可用模型

curl http://localhost:3000/ollama/api/tags \
  -H "Authorization: Bearer YOUR_API_KEY"

聊天接口

curl http://localhost:3000/ollama/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "[Claude] claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "你好"}]
  }'

常见问题

Q: 请求返回 404 错误怎么办？
A: 检查接口路径是否正确。某些客户端会自动在 Base URL 后追加路径，导致路径重复。请查看控制台中的实际请求 URL，移除多余的路径部分。
Q: 请求返回 429 错误怎么办？
A: 429 表示请求频率过高。建议配置多个账号到提供商池，启用轮询机制；或配置 Fallback 链实现跨类型降级。
Q: OAuth 授权失败怎么办？
A: 确保 OAuth 回调端口可访问（Gemini: 8085, Antigravity: 8086, Kiro: 19876-19880）。Docker 用户需确保已正确映射这些端口。
Q: 流式响应中断怎么办？
A: 检查网络稳定性，增加客户端请求超时时间。如使用代理，确保代理支持长连接。