xmAI Docs

English

中文

English

中文

Appearance

Integrating with Gemini CLI ​

Native CLI support is limited

Gemini CLI natively speaks the Google GLA / Vertex protocol only, which is not a 1:1 match for xmAI's OpenAI-compatible or Anthropic-compatible endpoints. The recommended path is to call Gemini models through xmAI's OpenAI-compatible API using a different CLI, rather than trying to force Gemini CLI itself onto xmAI.

This page documents two practical paths. Path A is strongly recommended. Path B covers the edge case where you must keep Gemini CLI as your client.

xmAI routes any of its OpenAI-compatible clients to Google GLA / Vertex when you pick a Gemini model ID. You do not need Gemini CLI for this.

Pick one of these clients:

Minimal SDK examples ​

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": "Summarize the Gemini 2.5 Pro announcement."}],
)
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: 'Summarize the Gemini 2.5 Pro announcement.' }],
})
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": "Summarize the Gemini 2.5 Pro announcement."}]
  }'

xmAI receives the OpenAI-style request, translates it to the native Google GLA / Vertex protocol internally, and returns a Chat Completions-shaped response. Streaming, system prompts, tools, and temperature controls all work.

Gemini models available on xmAI ​

xmAI model IDVendor modelNotes
gemini-2.5-proGemini 2.5 ProLong-context, reasoning-focused
gemini-2.5-flashGemini 2.5 FlashFast / low-cost

/v1/models is authoritative. If an ID returns 404 model not found, check the model list in Admin → Models or hit curl https://api.xmai.sg/v1/models with your key.

Path B — Keep using Gemini CLI itself ​

Gemini CLI expects Google GLA / Vertex endpoints. At the time of writing, its upstream does not expose a first-class customEndpoint flag for arbitrary OpenAI-compatible backends; the only official backends are:

  • Personal Google account + GEMINI_API_KEY (AI Studio)
  • Vertex AI (GOOGLE_GENAI_USE_VERTEXAI=true with GCP auth)

There is no stable, officially-supported way to point Gemini CLI at xmAI today. If you must try, consider these options — all unsupported, use at your own risk:

Option B-1 — Fork Gemini CLI to patch the endpoint ​

The Gemini CLI source hardcodes the generativelanguage.googleapis.com host. Forking and replacing the base URL with something that translates Google GLA → OpenAI is a non-trivial engineering project (the protocol, auth header, SSE envelope, and tool-use formats all differ). We don't recommend this unless you have a compelling reason.

Option B-2 — Watch upstream for a custom endpoint flag ​

Track these upstream issues / discussions:

If upstream lands a GEMINI_API_BASE_URL environment variable (or similar) that allows redirecting traffic to an OpenAI-compatible gateway with matching wire format, it still won't work against xmAI directly because xmAI's /v1/chat/completions is OpenAI-shaped, not Google GLA-shaped.

A working setup would require one of:

  • xmAI shipping a native /v1beta/models/:model:generateContent endpoint that mirrors Google GLA (tracked as a future story; not on the current roadmap)
  • A protocol-translation proxy between Gemini CLI and xmAI (community tools exist, none officially endorsed)

Option B-3 — Keep Gemini CLI for its original upstream, use xmAI elsewhere ​

The pragmatic choice: let Gemini CLI talk to Google AI Studio with its own GEMINI_API_KEY, and use another OpenAI-compatible CLI (OpenCode / Codex / Cursor) via xmAI for everything else. You lose nothing — xmAI gives you the same Gemini models through OpenAI Chat Completions without the protocol mismatch.

Verifying the connection (Path A) ​

After sending a test request via the SDK or your chosen OpenAI-compatible CLI:

  1. Log into the Console → Request Logs to confirm the request landed
  2. Or watch the Today's Usage card on the Dashboard for credit consumption

A new row in the log = you're connected.

Troubleshooting ​

404 model not found for gemini-2.5-pro ​

  • Hit curl https://api.xmai.sg/v1/models with your key to confirm the exact ID onboarded in your xmAI tenant — model IDs can vary by environment.
  • If Gemini isn't onboarded yet, request it via Admin → Models.

Tool-use / function-calling quirks ​

OpenAI → Google tool-schema translation strips JSON Schema keywords that Gemini doesn't accept (see Story 3-4 / gateway transform layer). Most simple schemas work; deeply nested oneOf / allOf / $ref may be simplified. If a tool schema breaks, log the request on Request Logs and file a ticket.

Gemini CLI returns permission denied or GCP auth errors ​

Those errors come from Google's backend, not xmAI — Gemini CLI never talked to xmAI in the first place (see Path B caveats above). Switch to Path A.

402 insufficient balance ​

xmAI deducts per-token in real time. When your balance runs out, requests return 402 or insufficient_balance. Top up on the wallet page, or enable auto-topup.

Connection / TLS errors ​

System proxy interference: If http_proxy / https_proxy are set, they may intercept xmAI traffic:

bash
export NO_PROXY="api.xmai.sg"

Self-signed certificates: In corporate networks with custom CA chains:

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

The Unified API for LLMs

© 2025 xmai.sg