docs/API_REFERENCE.md

API Reference (v4.1.32)

本文档详细介绍了 Antigravity Tools 暴露的 HTTP API 接口。

注意: 在 v4.0.1 版本中，所有的服务（包括 AI 反代和系统管理）均已整合至统一端口 8045。原有的 19527 端口已废弃。

1. 概览 (Overview)

Antigravity Gateway 是一个双重角色的服务器：

1. AI Proxy Interface: 兼容 OpenAI/Anthropic/Google 官方 SDK 的标准接口。
2. Management Admin API: 用于管理账号、配置系统、监控流量的 RESTful 接口。

鉴权体系 (Authentication)

接口类型	路径前缀	鉴权方式	Header 示例	说明
AI Protocol	/v1/*, /v1beta/*	API Key	Authorization: Bearer <API_KEY>	用于 AI 客户端调用
Admin API	/api/*	Admin Token	x-admin-token: <TOKEN>	用于管理后台或脚本控制

提示: 默认情况下，Admin Token 与 API Key 是同一个值（即您在 .env 或 Docker 环境变量中设置的 API_KEY）。

---

2. 管理接口 (Management API)

Base URL: http://<host>:8045/api

2.1 账号管理 (Account Management)

方法	路径	说明	参数示例
GET	/accounts	获取账号列表	-
GET	/accounts/current	获取当前活跃账号	-
POST	/accounts	添加账号 (OAuth Refresh Token)	{"refreshToken": "..."}
DELETE	/accounts/:id	删除账号	-
POST	/accounts/switch	切换活跃账号	{"accountId": "acc_123"}
POST	/accounts/refresh	刷新所有账号配额	-
GET	/accounts/:id/quota	查询特定账号配额	-
POST	/accounts/:id/toggle-proxy	禁用/启用账号代理	-
POST	/accounts/:id/bind-device	绑定设备指纹	{"mode": "generate"}
POST	/accounts/bulk-delete	批量删除账号	{"accountIds": ["id1", "id2"]}
POST	/accounts/reorder	账号排序	{"accountIds": [...]}

2.2 系统配置 (System Config)

方法	路径	说明
GET	/config	获取全量配置
POST	/config	保存全量配置
GET	/proxy/status	获取反代服务运行状态
POST	/proxy/start	启动反代服务
POST	/proxy/stop	停止反代服务
POST	/proxy/mapping	更新模型映射规则
GET	/health	系统健康检查

2.3 监控与统计 (Monitoring & Stats)

流量日志

• GET /logs: 获取日志列表 (支持 limit, offset, filter, errorsOnly 参数)
• GET /logs/count: 获取日志总数
• GET /logs/:id: 获取日志详情
• POST /logs/clear: 清空日志

Token 统计 (v4.0.1 New)

• GET /stats/token/summary: 获取 Token 消耗摘要 (今日/本周/总量)
• GET /stats/token/hourly: 获取按小时统计数据
• GET /stats/token/daily: 获取按日统计数据
• GET /stats/token/by-account: 按账号统计消耗占比
• GET /stats/token/by-model: 按模型统计消耗占比
• POST /stats/token/clear: 重置统计数据

2.4 高级功能 (Advanced)

• POST /proxy/cli/sync: 执行 CLI (Claude/Codex) 配置文件同步
• POST /accounts/import/db: 从 v1 旧数据库导入账号
• POST /accounts/oauth/start: 发起 OAuth 授权流程 (Headless)
• POST /proxy/cloudflared/start: 启动 Cloudflare Tunnel

---

3. AI 协议接口 (AI Protocol Interface)

Base URL: http://<host>:8045

本服务完全兼容主流 AI 厂商的官方协议规范。您可以直接将本服务的地址填入到支持 OpenAI / Claude 的客户端中。

OpenAI Compatible

• 对话生成 (Chat Completions)

  • POST /v1/chat/completions
  • 支持模型: 任何映射后的模型 ID (如 gpt-4o, gemini-1.5-pro)
  • 兼容性: 完全兼容 OpenAI 官方 Response 格式 (包括流式 SSE)。

• 图片生成 (Image Generation)

  • POST /v1/images/generations
  • 支持模型: gemini-3-pro-image (自动映射到 Imagen 3)
  • 参数扩展: 支持 size: "1920x1080", quality: "hd" 等高级参数。

Anthropic Compatible

• Claude Messages
  • POST /v1/messages
  • 用途: 支持 Claude CLI (claude), Cursor, Cherry Studio 等客户端。
  • 特性: 完整支持 Tool Use (工具调用) 和 Thinking (思维链) 模式。

Gemini Native

• Google AI Studio
  • GET/POST /v1beta/models/*
  • 用途: 供使用 Google 官方 SDK (Python/Node.js) 的应用调用。