Copilot API端点参考:OpenAI、Responses与Anthropic兼容接口全解
Copilot API端点参考:OpenAI、Responses与Anthropic兼容接口全解
Copilot API 是一个本地 AI 网关,在同一个本地端点上提供 OpenAI 兼容 Chat Completions、OpenAI Responses 与 Anthropic Messages 三大协议接口,把 Claude Code、Codex、OpenCode 等客户端的请求统一路由到 GitHub Copilot、内置 Codex、xAI 或第三方 provider。本文带你完整梳理它的全部 API 端点——从 OpenAI 兼容接口到 Anthropic 兼容接口,再到用量监控与管理配置端点——一次看懂请求该发到哪里。
🧭 网关概览:一个本地端点,多种 AI 后端
启动后,Copilot API 默认监听 http://localhost:4141,所有协议共用这一个地址:
- 客户端负责"怎么问":选择 Chat Completions、Responses 或 Messages 任一协议;
- 网关负责"谁来答":根据模型名或
provider/model别名,路由到 GitHub Copilot、内置codex、xai或已配置的第三方 provider,并在协议不同时自动完成翻译; - 流式输出全支持:三种协议都支持 SSE 流式返回。
用一条命令即可确认网关已启动:
curl http://localhost:4141/
# 返回:Server running
所有路由都集中注册在 server.ts 中,方便对照本文逐条查看。
🔑 认证方式:两种请求头任选
网关的普通路由在配置了 auth.apiKeys 后需要认证,支持以下两种请求头:
x-api-key: <your_key>Authorization: Bearer <your_key>
两点需要注意:
- Admin 路由例外:所有
/admin/*端点只接受auth.adminApiKey,缺失时服务会在启动时自动生成并写回config.json; - CORS 预检放行:
OPTIONS请求始终允许,浏览器客户端无需额外处理。
curl http://localhost:4141/v1/models \
-H "x-api-key: your_api_key"
💡 未配置普通 key 时(本机回环运行),普通路由可直接访问;
/admin/*不受此宽松规则影响。
📡 OpenAI 兼容端点详解
这是最常用的一组端点,模拟 OpenAI API 的标准结构:
POST /v1/chat/completions
为聊天对话创建模型响应,对应 OpenAI 最经典的接口。支持 openai-compatible provider 的 provider/model 别名,即目标 provider 已配置时,无需 GitHub Copilot 也能使用。
GET /v1/models
列出 Copilot 模型以及已启用 provider 的 provider/model-id 模型。有趣的是,该端点会识别客户端身份:来自 Codex 客户端(User-Agent 以 codex 开头)的请求会转发到 Codex Models 上游,Claude Code 与 OpenCode 客户端则获得各自适配的模型目录(见 models/route.ts)。
POST /v1/responses
OpenAI 新一代的 Responses 接口,用于生成模型响应。相比 Chat Completions 有两个加分项:
- 支持
Content-Encoding: zstd压缩请求体,适合长上下文场景(解压逻辑见 zstd-request.ts); - 支持
openai-responsesprovider 的别名路由。
POST /v1/embeddings
为输入文本创建向量嵌入,供 RAG、语义检索等场景使用,端点实现在 embeddings/route.ts。
以上每个
/v1/...端点也都支持不带前缀的/:path形式,如/chat/completions、/models。
🐙 Anthropic 兼容端点详解
这组端点按 Anthropic Messages API 的结构设计,是让 Claude Code 等 Anthropic 系客户端接入网关的关键:
POST /v1/messages
为对话创建模型响应。若请求来自 Anthropic 协议而上游 provider 使用 OpenAI 协议,网关会自动完成协议翻译,支持已配置 provider 的 provider/model 别名(含通过 openai-compatible provider 做翻译)。核心处理在 messages/handler.ts。
POST /v1/messages/count_tokens
轻量级接口,计算一组消息的 token 数,用于客户端预估上下文占用。
🎨 Codex 后端端点:图片生成与搜索
Copilot API 还实现了一组 Codex 后端 API,覆盖图片与搜索能力:
| 端点 | 说明 |
|---|---|
POST /v1/images/generations |
将图片生成请求转发到 Codex Images 上游,模型映射与 provider/model 别名同样生效 |
POST /v1/images/edits |
图片编辑,使用 multipart/form-data;大文件流式写入临时磁盘,总大小上限 128 MiB |
POST /v1/alpha/search |
将 Codex alpha-search 请求路由到 Codex 后端,或经由 Responses web-search 在本地处理 |
顶层图片请求要求已有可用的 Codex 登录态;路由到 Codex 后端的请求,网关会用当前 Codex 登录态覆盖客户端的鉴权头。
🧩 Provider 作用域路径:指定"由谁处理"
如果同时配置了多个 provider,可以用 provider 作用域路径 显式指定后端,避免歧义。上述每个 /v1/... 端点都支持 /:provider/v1/... 形式:
curl http://localhost:4141/kimi/v1/messages \
-H "x-api-key: your_api_key" \
-d '{ ... }'
其中 :provider 就是你在配置里定义的 provider 名称(如 kimi、openrouter、codex)。provider 级路径覆盖 messages、models、responses、images、alpha/search 五类端点,注册见 server.ts。
📊 使用量监控端点
网关内置了本地用量统计与 Copilot 配额查询两类端点:
GET /usage
获取 GitHub Copilot 的详细使用统计与额度信息,数据源在 usage/route.ts。
GET /token-usage 系列
基于本地 SQLite 统计网关自身的 Token 消耗,共四个子端点:
| 端点 | 说明 |
|---|---|
GET /token-usage |
汇总统计,支持 period 参数(today、last_7_days、this_month、lifetime 等) |
GET /token-usage/daily |
按天汇总 |
GET /token-usage/events |
分页的请求事件列表,支持 page 与 page_size |
GET /token-usage/sessions |
分页的会话维度统计 |
这些数据同时驱动了内置的 /usage-viewer 网页面板(该页面无需认证):
⚙️ Admin 配置端点
这组端点用于本地管理操作,只接受 auth.adminApiKey,适合桌面端或自动化脚本热更新配置:
| 端点 | 说明 |
|---|---|
GET /admin/config/model-mappings |
返回当前 config.json 路径与生效中的模型映射 |
POST /admin/config/model-mappings |
只更新 modelMappings 字段并回传最新结果 |
POST /admin/config/reload |
免重启重载配置,返回 { configPath, reloaded: true } |
实现见 admin/config/route.ts。修改 admin key 后,用修改前仍在生效的 key 发起刷新;无效 JSON 会保留上一次生效的配置。
📋 全部端点速查表
| 端点 | 方法 | 用途 |
|---|---|---|
/v1/chat/completions |
POST | OpenAI 聊天补全 |
/v1/models |
GET | 模型列表(按客户端适配) |
/v1/responses |
POST | OpenAI Responses,支持 zstd |
/v1/embeddings |
POST | 文本向量嵌入 |
/v1/messages |
POST | Anthropic Messages 兼容 |
/v1/messages/count_tokens |
POST | Token 计数 |
/v1/images/generations |
POST | 图片生成(Codex) |
/v1/images/edits |
POST | 图片编辑(Codex) |
/v1/alpha/search |
POST | Codex alpha-search |
/usage |
GET | Copilot 配额与用量 |
/token-usage 及子路径 |
GET | 本地 Token 消耗统计 |
/admin/config/* |
GET/POST | 模型映射与配置热重载 |
📌 除
/admin/*外,以上每个端点都有对应的/:provider/v1/...或/:provider/...变体,用于显式指定后端 provider。
📖 延伸阅读
- API 与认证完整文档:认证规则、模型发现来源与每个端点的详细说明
- 配置参考:
config.json全部配置项,包括 API Key、provider 定义与模型映射 - 命令行参考:
start、auth、debug子命令的完整参数 - 用量监控指南:用量面板的时间范围、指标卡与趋势图




