xAI Grok Provider

The xAI Grok provider contains language model support for the xAI API.

Setup

The xAI Grok provider is available via the @ai-sdk/xai module. You can install it with

pnpm

npm

yarn

pnpm add @ai-sdk/xai

Provider Instance

You can import the default provider instance xai from @ai-sdk/xai:

import { xai } from '@ai-sdk/xai';

If you need a customized setup, you can import createXai from @ai-sdk/xai and create a provider instance with your settings:

import { createXai } from '@ai-sdk/xai';

const xai = createXai({
  apiKey: 'your-api-key',
});

You can use the following optional settings to customize the xAI provider instance:

baseURL string

Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api.x.ai/v1.
apiKey string

API key that is being sent using the Authorization header. It defaults to the XAI_API_KEY environment variable.
headers Record<string,string>

Custom headers to include in the requests.
fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Language Models

You can create xAI models using a provider instance. The first argument is the model id, e.g. grok-beta.

const model = xai('grok-3');

Example

You can use xAI language models to generate text with the generateText function:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai('grok-3'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

xAI language models can also be used in the streamText, generateObject, and streamObject functions (see AI SDK Core).

Chat Models

xAI chat models also support some model specific provider options that are not part of the standard call settings. You can pass them in providerOptions argument:

const model = xai('grok-3');

await generateText({
  model,
  providerOptions: {
    xai: {
      user: 'test-user', // optional unique user identifier
    },
  },
});

The following optional provider options are available for xAI chat models:

user string

A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

xAI chat models also support some model specific provider options. You can pass them in providerOptions argument:

const model = xai('grok-3');

await generateText({
  model,
  providerOptions: {
    xai: {
      reasoningEffort: 'high',
    },
  },
});

The following optional provider options are available for xAI chat models:

reasoningEffort 'low' | 'medium' | 'high'

Reasoning effort for reasoning models. Defaults to medium. If you use providerOptions to set the reasoningEffort option, this model setting will be ignored.

Live Search

xAI models support Live Search functionality, allowing them to query real-time data from various sources and include it in responses with citations.

Basic Search

To enable search, specify searchParameters with a search mode:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: xai('grok-3-latest'),
  prompt: 'What are the latest developments in AI?',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'auto', // 'auto', 'on', or 'off'
        returnCitations: true,
        maxSearchResults: 5,
      },
    },
  },
});

console.log(text);
console.log('Sources:', sources);

Search Parameters

The following search parameters are available:

mode 'auto' | 'on' | 'off'

Search mode preference:
- 'auto' (default): Model decides whether to search
- 'on': Always enables search
- 'off': Disables search completely
returnCitations boolean

Whether to return citations in the response. Defaults to true.
fromDate string

Start date for search data in ISO8601 format (YYYY-MM-DD).
toDate string

End date for search data in ISO8601 format (YYYY-MM-DD).
maxSearchResults number

Maximum number of search results to consider. Defaults to 20, max 50.
sources array

Array of data sources to search from. Defaults to web and X if not specified.

Data Sources

You can specify which data sources to search from using the sources array:

Web Search

const result = await generateText({
  model: xai('grok-3-latest'),
  prompt: 'Best ski resorts in Switzerland',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'on',
        sources: [
          {
            type: 'web',
            country: 'CH', // ISO alpha-2 country code
            allowedWebsites: ['ski.com', 'snow-forecast.com'],
            safeSearch: true,
          },
        ],
      },
    },
  },
});

Web source parameters

country string: ISO alpha-2 country code
allowedWebsites string[]: Max 5 allowed websites (cannot be used with excludedWebsites)
excludedWebsites string[]: Max 5 excluded websites (cannot be used with allowedWebsites)
safeSearch boolean: Enable safe search (default: true)

X (Twitter) Search

const result = await generateText({
  model: xai('grok-3-latest'),
  prompt: 'Latest updates on Grok AI',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'on',
        sources: [
          {
            type: 'x',
            xHandles: ['grok', 'xai'],
          },
        ],
      },
    },
  },
});

X source parameters

xHandles string[]: Array of X/Twitter handles to search

News Search

const result = await generateText({
  model: xai('grok-3-latest'),
  prompt: 'Recent tech industry news',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'on',
        sources: [
          {
            type: 'news',
            country: 'US',
            excludedWebsites: ['tabloid.com'],
            safeSearch: true,
          },
        ],
      },
    },
  },
});

News source parameters

country string: ISO alpha-2 country code
excludedWebsites string[]: Max 5 excluded websites
safeSearch boolean: Enable safe search (default: true)

RSS Feed Search

const result = await generateText({
  model: xai('grok-3-latest'),
  prompt: 'Latest status updates',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'on',
        sources: [
          {
            type: 'rss',
            links: ['https://status.x.ai/feed.xml'],
          },
        ],
      },
    },
  },
});

RSS source parameters

links string[]: Array of RSS feed URLs (max 1 currently supported)

Multiple Sources

You can combine multiple data sources in a single search:

const result = await generateText({
  model: xai('grok-3-latest'),
  prompt: 'Comprehensive overview of recent AI breakthroughs',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'on',
        returnCitations: true,
        maxSearchResults: 15,
        sources: [
          {
            type: 'web',
            allowedWebsites: ['arxiv.org', 'openai.com'],
          },
          {
            type: 'news',
            country: 'US',
          },
          {
            type: 'x',
            xHandles: ['openai', 'deepmind'],
          },
        ],
      },
    },
  },
});

Sources and Citations

When search is enabled with returnCitations: true, the response includes sources that were used to generate the answer:

const { text, sources } = await generateText({
  model: xai('grok-3-latest'),
  prompt: 'What are the latest developments in AI?',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'auto',
        returnCitations: true,
      },
    },
  },
});

// Access the sources used
for (const source of sources) {
  if (source.sourceType === 'url') {
    console.log('Source:', source.url);
  }
}

Streaming with Search

Live Search works with streaming responses. Citations are included when the stream completes:

import { streamText } from 'ai';

const result = streamText({
  model: xai('grok-3-latest'),
  prompt: 'What has happened in tech recently?',
  providerOptions: {
    xai: {
      searchParameters: {
        mode: 'auto',
        returnCitations: true,
      },
    },
  },
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

console.log('Sources:', await result.sources);

Model Capabilities

Model	Image Input	Object Generation	Tool Usage	Tool Streaming
`grok-3`
`grok-3-fast`
`grok-3-mini`
`grok-3-mini-fast`
`grok-2-1212`
`grok-2-vision-1212`
`grok-beta`
`grok-vision-beta`

The table above lists popular models. Please see the xAI docs for a full list of available models. The table above lists popular models. You can also pass any available provider model ID as a string if needed.

Image Models

You can create xAI image models using the .imageModel() factory method. For more on image generation with the AI SDK see generateImage().

import { xai } from '@ai-sdk/xai';
import { experimental_generateImage as generateImage } from 'ai';

const { image } = await generateImage({
  model: xai.image('grok-2-image'),
  prompt: 'A futuristic cityscape at sunset',
});

The xAI image model does not currently support the aspectRatio or size parameters. Image size defaults to 1024x768.

Model-specific options

You can customize the image generation behavior with model-specific settings:

import { xai } from '@ai-sdk/xai';
import { experimental_generateImage as generateImage } from 'ai';

const { images } = await generateImage({
  model: xai.image('grok-2-image'),
  prompt: 'A futuristic cityscape at sunset',
  maxImagesPerCall: 5, // Default is 10
  n: 2, // Generate 2 images
});

Model Capabilities

Model	Sizes	Notes
`grok-2-image`	1024x768 (default)	xAI's text-to-image generation model, designed to create high-quality images from text prompts. It's trained on a diverse dataset and can generate images across various styles, subjects, and settings.