@ai-sdk/xai 3.0.30 → 3.0.32

package/docs/01-xai.mdx

@@ -0,0 +1,747 @@
+---
+title: xAI Grok
+description: Learn how to use xAI Grok.
+---
+
+# xAI Grok Provider
+
+The [xAI Grok](https://x.ai) provider contains language model support for the [xAI API](https://x.ai/api).
+
+## Setup
+
+The xAI Grok provider is available via the `@ai-sdk/xai` module. You can
+install it with
+
+<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
+  <Tab>
+    <Snippet text="pnpm add @ai-sdk/xai" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install @ai-sdk/xai" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add @ai-sdk/xai" dark />
+  </Tab>
+
+  <Tab>
+    <Snippet text="bun add @ai-sdk/xai" dark />
+  </Tab>
+</Tabs>
+
+## Provider Instance
+
+You can import the default provider instance `xai` from `@ai-sdk/xai`:
+
+```ts
+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:
+
+```ts
+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&lt;string,string&gt;_
+
+  Custom headers to include in the requests.
+
+- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_
+
+  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/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](https://console.x.ai) using a provider instance. The
+first argument is the model id, e.g. `grok-3`.
+
+```ts
+const model = xai('grok-3');
+```
+
+By default, `xai(modelId)` uses the Chat API. To use the Responses API with server-side agentic tools, explicitly use `xai.responses(modelId)`.
+
+### Example
+
+You can use xAI language models to generate text with the `generateText` function:
+
+```ts
+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](/docs/ai-sdk-core)).
+
+### Provider Options
+
+xAI chat models support additional provider options that are not part of
+the [standard call settings](/docs/ai-sdk-core/settings). You can pass them in the `providerOptions` argument:
+
+```ts
+const model = xai('grok-3-mini');
+
+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.
+
+- **store** _boolean_
+
+  Whether to store the generation. Defaults to `true`.
+
+- **previousResponseId** _string_
+
+  The ID of the previous response. You can use it to continue a conversation. Defaults to `undefined`.
+
+## Responses API (Agentic Tools)
+
+You can use the xAI Responses API with the `xai.responses(modelId)` factory method for server-side agentic tool calling. This enables the model to autonomously orchestrate tool calls and research on xAI's servers.
+
+```ts
+const model = xai.responses('grok-4-fast');
+```
+
+The Responses API provides server-side tools that the model can autonomously execute during its reasoning process:
+
+- **web_search**: Real-time web search and page browsing
+- **x_search**: Search X (Twitter) posts, users, and threads
+- **code_execution**: Execute Python code for calculations and data analysis
+- **mcp_server**: Connect to remote MCP servers and use their tools
+
+### Vision
+
+The Responses API supports image input with vision models:
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: xai.responses('grok-2-vision-1212'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What do you see in this image?' },
+        { type: 'image', image: fs.readFileSync('./image.png') },
+      ],
+    },
+  ],
+});
+```
+
+### Web Search Tool
+
+The web search tool enables autonomous web research with optional domain filtering and image understanding:
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { generateText } from 'ai';
+
+const { text, sources } = await generateText({
+  model: xai.responses('grok-4-fast'),
+  prompt: 'What are the latest developments in AI?',
+  tools: {
+    web_search: xai.tools.webSearch({
+      allowedDomains: ['arxiv.org', 'openai.com'],
+      enableImageUnderstanding: true,
+    }),
+  },
+});
+
+console.log(text);
+console.log('Citations:', sources);
+```
+
+#### Web Search Parameters
+
+- **allowedDomains** _string[]_
+
+  Only search within specified domains (max 5). Cannot be used with `excludedDomains`.
+
+- **excludedDomains** _string[]_
+
+  Exclude specified domains from search (max 5). Cannot be used with `allowedDomains`.
+
+- **enableImageUnderstanding** _boolean_
+
+  Enable the model to view and analyze images found during search. Increases token usage.
+
+### X Search Tool
+
+The X search tool enables searching X (Twitter) for posts, with filtering by handles and date ranges:
+
+```ts
+const { text, sources } = await generateText({
+  model: xai.responses('grok-4-fast'),
+  prompt: 'What are people saying about AI on X this week?',
+  tools: {
+    x_search: xai.tools.xSearch({
+      allowedXHandles: ['elonmusk', 'xai'],
+      fromDate: '2025-10-23',
+      toDate: '2025-10-30',
+      enableImageUnderstanding: true,
+      enableVideoUnderstanding: true,
+    }),
+  },
+});
+```
+
+#### X Search Parameters
+
+- **allowedXHandles** _string[]_
+
+  Only search posts from specified X handles (max 10). Cannot be used with `excludedXHandles`.
+
+- **excludedXHandles** _string[]_
+
+  Exclude posts from specified X handles (max 10). Cannot be used with `allowedXHandles`.
+
+- **fromDate** _string_
+
+  Start date for posts in ISO8601 format (`YYYY-MM-DD`).
+
+- **toDate** _string_
+
+  End date for posts in ISO8601 format (`YYYY-MM-DD`).
+
+- **enableImageUnderstanding** _boolean_
+
+  Enable the model to view and analyze images in X posts.
+
+- **enableVideoUnderstanding** _boolean_
+
+  Enable the model to view and analyze videos in X posts.
+
+### Code Execution Tool
+
+The code execution tool enables the model to write and execute Python code for calculations and data analysis:
+
+```ts
+const { text } = await generateText({
+  model: xai.responses('grok-4-fast'),
+  prompt:
+    'Calculate the compound interest for $10,000 at 5% annually for 10 years',
+  tools: {
+    code_execution: xai.tools.codeExecution(),
+  },
+});
+```
+
+### MCP Server Tool
+
+The MCP server tool enables the model to connect to remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers and use their tools:
+
+```ts
+const { text } = await generateText({
+  model: xai.responses('grok-4-fast'),
+  prompt: 'Use the weather tool to check conditions in San Francisco',
+  tools: {
+    weather_server: xai.tools.mcpServer({
+      serverUrl: 'https://example.com/mcp',
+      serverLabel: 'weather-service',
+      serverDescription: 'Weather data provider',
+      allowedTools: ['get_weather', 'get_forecast'],
+    }),
+  },
+});
+```
+
+#### MCP Server Parameters
+
+- **serverUrl** _string_ (required)
+
+  The URL of the remote MCP server.
+
+- **serverLabel** _string_ (required)
+
+  A label to identify the MCP server.
+
+- **serverDescription** _string_
+
+  A description of what the MCP server provides.
+
+- **allowedTools** _string[]_
+
+  List of tool names that the model is allowed to use from the MCP server. If not specified, all tools are allowed.
+
+- **headers** _Record&lt;string, string&gt;_
+
+  Custom headers to include when connecting to the MCP server.
+
+- **authorization** _string_
+
+  Authorization header value for authenticating with the MCP server (e.g., `'Bearer token123'`).
+
+### File Search Tool
+
+xAI supports file search through OpenAI compatibility. You can use the OpenAI provider with xAI's base URL to search vector stores:
+
+```ts
+import { createOpenAI } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+
+const openai = createOpenAI({
+  baseURL: 'https://api.x.ai/v1',
+  apiKey: process.env.XAI_API_KEY,
+});
+
+const result = streamText({
+  model: openai('grok-4'),
+  prompt: 'What documents do you have access to?',
+  tools: {
+    file_search: openai.tools.fileSearch({
+      vectorStoreIds: ['your-vector-store-id'],
+      maxNumResults: 5,
+    }),
+  },
+});
+```
+
+<Note>
+  File search requires grok-4 family models. See the [OpenAI
+  provider](/providers/ai-sdk-providers/openai) documentation for additional
+  file search options like filters and ranking.
+</Note>
+
+### Multiple Tools
+
+You can combine multiple server-side tools for comprehensive research:
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { streamText } from 'ai';
+
+const { fullStream } = streamText({
+  model: xai.responses('grok-4-fast'),
+  prompt: 'Research AI safety developments and calculate risk metrics',
+  tools: {
+    web_search: xai.tools.webSearch(),
+    x_search: xai.tools.xSearch(),
+    code_execution: xai.tools.codeExecution(),
+    data_service: xai.tools.mcpServer({
+      serverUrl: 'https://data.example.com/mcp',
+      serverLabel: 'data-service',
+    }),
+  },
+});
+
+for await (const part of fullStream) {
+  if (part.type === 'text-delta') {
+    process.stdout.write(part.text);
+  } else if (part.type === 'source' && part.sourceType === 'url') {
+    console.log('\nSource:', part.url);
+  }
+}
+```
+
+### Provider Options
+
+The Responses API supports the following provider options:
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: xai.responses('grok-4-fast'),
+  providerOptions: {
+    xai: {
+      reasoningEffort: 'high',
+    },
+  },
+  // ...
+});
+```
+
+The following provider options are available:
+
+- **reasoningEffort** _'low' | 'high'_
+
+  Control the reasoning effort for the model. Higher effort may produce more thorough results at the cost of increased latency and token usage.
+
+<Note>
+  The Responses API only supports server-side tools. You cannot mix server-side
+  tools with client-side function tools in the same request.
+</Note>
+
+## 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:
+
+```ts
+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&lt;SearchSource&gt;_
+
+  Data sources to search from. Defaults to `["web", "x"]` if not specified.
+
+### Search Sources
+
+You can specify different types of data sources for search:
+
+#### Web Search
+
+```ts
+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
+- **excludedWebsites** _string[]_: Max 5 excluded websites
+- **safeSearch** _boolean_: Enable safe search (default: true)
+
+#### X (Twitter) Search
+
+```ts
+const result = await generateText({
+  model: xai('grok-3-latest'),
+  prompt: 'Latest updates on Grok AI',
+  providerOptions: {
+    xai: {
+      searchParameters: {
+        mode: 'on',
+        sources: [
+          {
+            type: 'x',
+            includedXHandles: ['grok', 'xai'],
+            excludedXHandles: ['openai'],
+            postFavoriteCount: 10,
+            postViewCount: 100,
+          },
+        ],
+      },
+    },
+  },
+});
+```
+
+#### X source parameters
+
+- **includedXHandles** _string[]_: Array of X handles to search (without @ symbol)
+- **excludedXHandles** _string[]_: Array of X handles to exclude from search (without @ symbol)
+- **postFavoriteCount** _number_: Minimum favorite count of the X posts to consider.
+- **postViewCount** _number_: Minimum view count of the X posts to consider.
+
+#### News Search
+
+```ts
+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
+
+```ts
+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:
+
+```ts
+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',
+            includedXHandles: ['openai', 'deepmind'],
+          },
+        ],
+      },
+    },
+  },
+});
+```
+
+### Sources and Citations
+
+When search is enabled with `returnCitations: true`, the response includes sources that were used to generate the answer:
+
+```ts
+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:
+
+```ts
+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      | Reasoning           |
+| --------------------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `grok-4-fast-non-reasoning` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-4-fast-reasoning`     | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `grok-code-fast-1`          | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `grok-4`                    | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-3`                    | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-3-latest`             | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-3-fast`               | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-3-fast-latest`        | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-3-mini`               | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `grok-3-mini-latest`        | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `grok-3-mini-fast`          | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `grok-3-mini-fast-latest`   | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `grok-2`                    | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-2-latest`             | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-2-1212`               | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-2-vision`             | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-2-vision-latest`      | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-2-vision-1212`        | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-beta`                 | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `grok-vision-beta`          | <Check size={18} /> | <Cross size={18} /> | <Cross size={18} /> | <Cross size={18} /> | <Cross size={18} /> |
+
+<Note>
+  The table above lists popular models. Please see the [xAI
+  docs](https://docs.x.ai/docs#models) for a full list of available models. You
+  can also pass any available provider model ID as a string if needed.
+</Note>
+
+## Image Models
+
+You can create xAI image models using the `.image()` factory method. For more on image generation with the AI SDK see [generateImage()](/docs/reference/ai-sdk-core/generate-image).
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { generateImage } from 'ai';
+
+const { image } = await generateImage({
+  model: xai.image('grok-2-image'),
+  prompt: 'A futuristic cityscape at sunset',
+});
+```
+
+<Note>
+  The xAI image model does not currently support the `aspectRatio` or `size`
+  parameters. Image size defaults to 1024x768.
+</Note>
+
+### Model-specific options
+
+You can customize the image generation behavior with model-specific settings:
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { 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. |