Copilot API端点参考:OpenAI、Responses与Anthropic兼容接口全解

原创2026-10-15 06:32:051,848 阅读

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 流式返回。

Copilot API 桌面端网关仪表盘

用一条命令即可确认网关已启动:

curl http://localhost:4141/
# 返回:Server running

所有路由都集中注册在 server.ts 中,方便对照本文逐条查看。

🔑 认证方式:两种请求头任选

网关的普通路由在配置了 auth.apiKeys 后需要认证,支持以下两种请求头:

  • x-api-key: <your_key>
  • Authorization: Bearer <your_key>

两点需要注意:

  1. Admin 路由例外:所有 /admin/* 端点只接受 auth.adminApiKey,缺失时服务会在启动时自动生成并写回 config.json;
  2. 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)。

Codex 客户端的模型列表界面

POST /v1/responses

OpenAI 新一代的 Responses 接口,用于生成模型响应。相比 Chat Completions 有两个加分项:

  • 支持 Content-Encoding: zstd 压缩请求体,适合长上下文场景(解压逻辑见 zstd-request.ts);
  • 支持 openai-responses provider 的别名路由。

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 数,用于客户端预估上下文占用。

Copilot API 桌面端 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 API 桌面端 Provider 管理界面

📊 使用量监控端点

网关内置了本地用量统计与 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 网页面板(该页面无需认证):

Copilot API 用量查看器页面

⚙️ 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。

📖 延伸阅读

登录后查看全文
copilot-api