xAI Grok

xAI / Grok

ChatHub talks to official xAI Grok models as a first-class xAI provider (xai). Model ids stay grok-*. v1 is chat only (text, vision, tools, reasoning). Grok Imagine image/video and Voice APIs are not included.

Official Console inference uses https://api.x.ai/v1. Chat Completions is the ChatHub default; Settings can opt into Responses (/v1/responses).

Console API key

1. Open Settings → xAI.
2. Paste a Console API key from xAI Console.
3. Leave the proxy blank to use https://api.x.ai/v1, or set XAI_PROXY_URL / the proxy field.
4. Enable the provider. The default connection check uses grok-4.7. The checker model menu can select grok-4.7-build-fast and run Check. A Console API key may reject Build Fast. A SuperGrok session can accept it.

Browser requests stay off so keys never go through the tab.

SuperGrok device login (Settings only)

Each account can click Sign in with SuperGrok on Settings → xAI and pay chat from that user's SuperGrok quota. The API key and proxy fields stay on the same page. Sign-out returns chat to the Console key.

This is an unofficial shared Grok CLI client. Consent may show Grok Build. xAI can change the public client or the consumer proxy at any time.

1. Open Settings → xAI.
2. Keep or fill the API key / proxy if you still need a Console fallback.
3. Click Sign in with SuperGrok.
4. ChatHub shows a device code. Open the xAI device page (Open Grok authorization) and enter the code.
5. After authorization, the card shows the connected email, plan tag when present, the weekly SuperGrok remaining bar, and the session expiry. A 5-hour bar appears only if SuperGrok reports a second ~5-hour window. Unofficial-client notes live on the title help icon.

Leaving Settings or the xAI page stops the waiting poll. Click Sign in with SuperGrok again if you still need to authorize. If a server restart interrupts sign-in, wait for the device code to expire, then sign in again. ChatHub does not take over an in-flight SuperGrok grant.

There is no chat-input OAuth button and no instance-wide shared SuperGrok login.

Quota vs API key

Surface	While SuperGrok is signed in	After sign-out
xAI chat (including background Graphile turns)	SuperGrok / cli-chat-proxy.grok.com	Console API key or XAI_API_KEY
Structured object generation	Console API key	Console API key
Images / Voice	Not in this release	Not in this release

While a SuperGrok session is connected, ChatHub forces server-side fetch so tokens never leave the server. Temporary refresh failures keep the session and do not silently bill Console. Confirmed invalid refresh tokens disconnect and the next chat can use the API key.

If chat keeps failing with a temporary SuperGrok refresh error after an interrupted refresh or container restart, Settings can still show connected. Waiting or restarting does not clear that stuck refresh owner. Sign out of SuperGrok, then sign in again. Chat then uses the Console API key until the new SuperGrok session is live.

If SuperGrok chat says your Grok CLI version is outdated, that string is ChatHub's pinned client header. Update ChatHub. Do not run grok update on the host.

Usage meters

Official SuperGrok is a weekly pool (Grok FAQ). ChatHub reads GET /v1/billing?format=credits on the consumer proxy with the stored SuperGrok token.

• Weekly (or Monthly if that is what the payload says) is shown when the billing response includes a period or a used percent.
• The used percent comes from creditUsagePercent when present. If that field is omitted, ChatHub uses onDemandUsed / onDemandCap when the cap is greater than zero. It does not invent 0% for a missing percent.
• When SuperGrok returns a weekly period but no percent, the weekly row still appears with the reset time and an explicit “not reported” note instead of hiding the bar.
• A 5-hour meter is shown only when a second window is actually present.
• A failed usage lookup does not sign you out.
• Console API-key setups have no SuperGrok meters.

The same Settings page has a separate Balance & usage card. It shows prepaid balance for an xAI management key and does not replace the SuperGrok meters. See Model Providers.

Reasoning and search

The model gear (when present) maps official Grok effort:

• grok-4.7 and grok-4.7-build-fast: low / medium / high / xhigh (thinking cannot be disabled). Build Fast is the same model on faster serving. The public models table does not list that id; SuperGrok model fetch does.
• grok-4.6: low / medium / high / xhigh (thinking cannot be disabled)
• grok-4.5: low / medium / high
• grok-4.3: none / low / medium / high (none is sent as reasoning_effort: none; it does not omit the field)

Native Grok search stays opt-in on the search panel. Select Responses first, then turn on the model's built-in search toggle. ChatHub then sends tools: [{ type: "web_search" }]. Chat Completions does not invent a search field.

xAI Responses rejects Chat Completions max_tokens. ChatHub maps the token budget to max_output_tokens on /v1/responses and keeps max_tokens on Chat Completions.

Prompt cache debug

xAI prefix cache is automatic. ChatHub also sends a trusted conversation id:

• Chat Completions: header x-grok-conv-id
• Responses: body prompt_cache_key

Set DEBUG_XAI_CACHE=1 (plus KEY_VAULTS_SECRET or NEXT_AUTH_SECRET) to log cache-key / header presence + hash and cached_tokens, not raw ids. DEBUG_XAI_CHAT_COMPLETION=1 and DEBUG_XAI_RESPONSES=1 are transport dumps. CHATHUB_XAI_OAUTH_DEBUG=1 logs safe SuperGrok login/refresh/billing metadata.

See Debug and Diagnostics.

Limits

• Chat streaming only in the SuperGrok overlay.
• Tokens are stored encrypted on the server (xai_oauth_tokens). They are never written to keyVaults or sent to the browser.