xmAI Docs

中文

English

中文

English

Appearance

接入 Gemini CLI ​

原生 CLI 支持有限

Gemini CLI 原生仅支持 Google GLA / Vertex 协议，与 xmAI 的 OpenAI 兼容 / Anthropic 兼容端点 不是 1:1 对等。推荐做法是 通过 xmAI 的 OpenAI 兼容端点、选用 Gemini 模型，而不是把 Gemini CLI 当作主用客户端。

本页给出两条可行路径。路径 A 强烈推荐。 路径 B 针对必须保留 Gemini CLI 的边缘场景。

路径 A（推荐）— 改用 OpenAI 兼容 CLI，通过 xmAI 调 Gemini 模型 ​

当你在 OpenAI 兼容客户端里选 Gemini model ID 时，xmAI 会自动把请求转译到 Google GLA / Vertex 后返回 Chat Completions 格式结果。你无需 Gemini CLI 本身即可完整使用 Gemini 模型。

可以任选一个客户端：

最小 SDK 示例 ​

python
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-xmai-key",
    base_url="https://api.xmai.sg/v1",
)

response = client.chat.completions.create(
    model="gemini-2.5-pro",
    messages=[{"role": "user", "content": "总结一下 Gemini 2.5 Pro 的发布要点。"}],
)
print(response.choices[0].message.content)
javascript
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'sk-your-xmai-key',
  baseURL: 'https://api.xmai.sg/v1',
})

const response = await client.chat.completions.create({
  model: 'gemini-2.5-pro',
  messages: [{ role: 'user', content: '总结一下 Gemini 2.5 Pro 的发布要点。' }],
})
console.log(response.choices[0].message.content)
bash
curl https://api.xmai.sg/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-xmai-key" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [{"role": "user", "content": "总结一下 Gemini 2.5 Pro 的发布要点。"}]
  }'

xmAI 收到 OpenAI 风格请求后 内部转译为原生 Google GLA / Vertex 协议，再以 Chat Completions 格式返回。流式、system prompt、tools、温度参数均可用。

xmAI 上架的 Gemini 模型 ​

xmAI model ID官方模型说明
gemini-2.5-proGemini 2.5 Pro长上下文 / 推理导向
gemini-2.5-flashGemini 2.5 Flash快速 / 低成本

/v1/models 为权威来源。若某个 ID 报 404 model not found，请在 Admin → 模型管理 确认上架状态，或使用 curl https://api.xmai.sg/v1/models 自查。

路径 B — 坚持使用 Gemini CLI 本身 ​

Gemini CLI 只认 Google GLA / Vertex 端点。当前上游 没有一等公民式的 customEndpoint 开关 支持任意 OpenAI 兼容后端，官方只认：

  • 个人 Google 账号 + GEMINI_API_KEY（AI Studio）
  • Vertex AI（GOOGLE_GENAI_USE_VERTEXAI=true + GCP 认证）

目前没有稳定的官方方式把 Gemini CLI 指向 xmAI。如果你仍想尝试，下面几条路径 均非官方支持，风险自担：

方案 B-1 — Fork Gemini CLI 并打补丁改写端点 ​

Gemini CLI 源码硬编码了 generativelanguage.googleapis.com 主机。Fork 后把 base URL 替换为 能做 Google GLA → OpenAI 转译的中间层 是个 非平凡的工程项目（协议、认证头、SSE 封装、tool-use 格式全部不同）。除非有强需求否则不推荐。

方案 B-2 — 关注上游是否新增自定义端点开关 ​

跟踪以下上游动态：

即便上游未来新增 GEMINI_API_BASE_URL 一类环境变量允许重定向流量到 OpenAI 兼容网关，直接指向 xmAI 仍然行不通，因为 xmAI 的 /v1/chat/completions 是 OpenAI 格式而非 Google GLA 格式。

可行组合需满足 以下任一条件：

  • xmAI 上线原生 /v1beta/models/:model:generateContent 端点（镜像 Google GLA）— 作为后续独立 Story 跟踪，暂未排期
  • 在 Gemini CLI 与 xmAI 之间部署协议转译 Proxy（社区有方案但无官方背书）

方案 B-3 — Gemini CLI 保留原上游，其他场景用 xmAI ​

最务实的选择：让 Gemini CLI 使用官方 GEMINI_API_KEY 直连 Google AI Studio，其他 coding / agent 场景改用 OpenAI 兼容 CLI（OpenCode / Codex / Cursor）走 xmAI。能力不减 — xmAI 通过 OpenAI Chat Completions 给你同一批 Gemini 模型，还避开了协议不匹配的麻烦。

验证接入（路径 A） ​

通过 SDK 或任意 OpenAI 兼容 CLI 发一条测试请求后：

  1. 登录 XmAI 控制台 → 请求日志，查看是否有新记录
  2. 或在 Dashboard 的 本日消费 卡片观察 credits 变化

看到新请求即接入成功。

常见问题 ​

gemini-2.5-pro 报 404 model not found ​

  • 使用 curl https://api.xmai.sg/v1/models 带上你的 Key 确认当前租户实际上架的 ID — 不同环境可能不同
  • 若 Gemini 尚未上架，请到 Admin → 模型管理 提交接入请求

Tool-use / function-calling 异常 ​

OpenAI → Google tool schema 转译会剥离 Gemini 不接受的 JSON Schema 关键字（见 Story 3-4 / 网关转换层）。大多数简单 schema 可用；深层嵌套的 oneOf / allOf / $ref 可能被简化。若 tool schema 损坏，请求日志 查到请求后提 Ticket。

Gemini CLI 报 permission denied 或 GCP 认证错误 ​

这类错误来自 Google 后端，与 xmAI 无关 — Gemini CLI 根本没走到 xmAI（见路径 B 警告）。请切换到路径 A。

402 余额不足 ​

xmAI 按 token 实时扣费，余额不足会返回 402 或 insufficient_balance。前往 钱包页面 补充额度，或开启自动充值。

连接失败 / 证书错误 ​

系统代理干扰： 若设置了 http_proxy / https_proxy，可能拦截 xmAI 流量：

bash
export NO_PROXY="api.xmai.sg"

自签名证书： 企业内网若走了自有证书链：

bash
export NODE_EXTRA_CA_CERTS=/path/to/your-ca-chain.pem

相关链接 ​

The Unified API for LLMs

© 2025 xmai.sg