Skip to content
zidane
SDK reference

zidane/providers/xai

The xAI Grok provider, with an API key or SuperGrok OAuth credentials.

import { … } from 'zidane/providers/xai'src/providers/xai.ts

Use xai() when your agent talks to Grok. It reads XAI_API_KEY when you pass no key. Without a key, it uses the stored SuperGrok credentials and refreshes them on each turn. You can pick a stored account by name. See Providers.

TypeScript
import { createAgent } from 'zidane'
import { xai } from 'zidane/providers/xai'

const agent = createAgent({ provider: xai({ defaultModel: 'grok-4.6' }) })
const stats = await agent.run({ prompt: 'Summarize README.md in three bullets.' })
console.log(stats.turns)

Functions#

xaiFunction#

xAI Grok provider — supports both a static API key (XAI_API_KEY) and the SuperGrok / X Premium+ OAuth subscription.

Both auth modes hit the same OpenAI-compatible endpoint (https://api.x.ai/v1 unless XAI_BASE_URL or PI_XAI_BASE_URL overrides it), so the wire handling is entirely openaiCompat. The only difference is the bearer:

  • API key: XAI_API_KEY (or params.apiKey) → used verbatim.
  • OAuth: no static key → resolveOAuthApiKey resolves + lazily refreshes the stored xai-oauth token on every turn.

resolveOAuthApiKey unifies the two: a real API key in XAI_API_KEY is returned as-is, while an OAuth access token (or no env value at all) falls through to the refreshable stored credentials. So this single factory serves both paths without branching at construction time.

TypeScript
function xai(params?: XaiParams): Provider

Parameters

Parameters
NameTypeDescription
params?XaiParams

API key or OAuth credentials, default model, capabilities and extra headers.

Returns

Provider

Example

Example
import { createAgent } from 'zidane'
import { xai } from 'zidane/providers/xai'

const agent = createAgent({
  provider: xai({ apiKey: process.env.XAI_API_KEY }),
})
await agent.run({ prompt: 'Say hello.' })

src/providers/xai.ts:58

Interfaces#

XaiParamsInterface#

Options for xai.

TypeScript
interface XaiParams extends OAuthParams

Properties

XaiParams properties
NameTypeDefaultDescription
access?from OAuthParamsstring

OAuth access token supplied at runtime. Used together with refresh and expires to refresh without a credentials file.

account?from OAuthParamsstring

Run on ONE stored account of the provider instead of its active one: the credential's stable id (ProviderCredential.id, see chat/credentials). Resolved to the slot holding it on every token read and refresh, so promoting another account mid-session never moves this provider to it. The provider's env key is ignored while pinned (it is the active credential's, not this account's). A missing account fails the call with pinnedAccountMissingError — never a silent fallback to another account.

apiKey?from OAuthParamsstring

Static API key or OAuth access token sent as is, bypassing credential lookup and refresh.

capabilities?ProviderCapabilities

Provider capability flags. Grok models are vision-capable; default { vision: true, imageInToolResult: false }. Override for text-only deployments.

defaultModel?string'grok-4.6'

Model used when a request does not set one.

expires?from OAuthParamsnumber

Expiry of access as a Unix timestamp in milliseconds.

extraHeaders?Record<string, string>

Extra HTTP headers sent on every request.

refresh?from OAuthParamsstring

OAuth refresh token supplied at runtime.

src/providers/xai.ts:11