Grok (xAI)

The Grok adapter provides access to xAI's Grok models, including Grok 4.1, Grok 4, Grok 3, and image generation with Grok 2 Image.

Installation

shell

npm install @tanstack/ai-grok

Basic Usage

import { chat } from "@tanstack/ai";
import { grokText } from "@tanstack/ai-grok";

const stream = chat({
  adapter: grokText("grok-4"),
  messages: [{ role: "user", content: "Hello!" }],
});

Basic Usage - Custom API Key

import { chat } from "@tanstack/ai";
import { createGrokText } from "@tanstack/ai-grok";

const adapter = createGrokText("grok-4", process.env.XAI_API_KEY!);

const stream = chat({
  adapter,
  messages: [{ role: "user", content: "Hello!" }],
});

Configuration

import { createGrokText, type GrokTextConfig } from "@tanstack/ai-grok";

const config: Omit<GrokTextConfig, "apiKey"> = {
  baseURL: "https://api.x.ai/v1", // Optional, this is the default
};

const adapter = createGrokText("grok-4", process.env.XAI_API_KEY!, config);

Example: Chat Completion

import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { grokText } from "@tanstack/ai-grok";

export async function POST(request: Request) {
  const { messages } = await request.json();

  const stream = chat({
    adapter: grokText("grok-4"),
    messages,
  });

  return toServerSentEventsResponse(stream);
}

Example: With Tools

import { chat, toolDefinition } from "@tanstack/ai";
import { grokText } from "@tanstack/ai-grok";
import { z } from "zod";

const getWeatherDef = toolDefinition({
  name: "get_weather",
  description: "Get the current weather",
  inputSchema: z.object({
    location: z.string(),
  }),
});

const getWeather = getWeatherDef.server(async ({ location }) => {
  // Fetch weather data
  return { temperature: 72, conditions: "sunny" };
});

const stream = chat({
  adapter: grokText("grok-4-1-fast-reasoning"),
  messages,
  tools: [getWeather],
});

Model Options

Grok supports various provider-specific options. Sampling parameters live here too — temperature, top_p, and max_tokens — rather than as root-level props on chat():

const stream = chat({
  adapter: grokText("grok-4"),
  messages,
  modelOptions: {
    temperature: 0.7,
    top_p: 0.9,
    max_tokens: 1024,
    frequency_penalty: 0.5,
    presence_penalty: 0.5,
    stop: ["END"],
  },
});

If you previously passed temperature / topP / maxTokens at the root of chat(), see Moving Sampling Options into modelOptions.

Summarization

Summarize long text content:

import { summarize } from "@tanstack/ai";
import { grokSummarize } from "@tanstack/ai-grok";

const result = await summarize({
  adapter: grokSummarize("grok-4"),
  text: "Your long text to summarize...",
  maxLength: 100,
  style: "concise", // "concise" | "bullet-points" | "paragraph"
});

console.log(result.summary);

Image Generation

Generate images with Grok 2 Image:

import { generateImage } from "@tanstack/ai";
import { grokImage } from "@tanstack/ai-grok";

const result = await generateImage({
  adapter: grokImage("grok-2-image-1212"),
  prompt: "A futuristic cityscape at sunset",
  numberOfImages: 1,
});

console.log(result.images);

The grok-imagine models (grok-imagine-image, grok-imagine-image-quality) are aspect-ratio sized — size takes an aspectRatio_resolution template like "16:9_2k" (the _2k suffix is optional):

const result = await generateImage({
  adapter: grokImage("grok-imagine-image"),
  prompt: "A futuristic cityscape at sunset",
  size: "16:9_2k",
});

Image Editing (image-to-image)

The grok-imagine models accept image prompt parts for image-conditioned generation via xAI's /v1/images/edits endpoint — up to 3 source images, addressed by xAI in the order they appear in the prompt. Per xAI's docs there is no in-prompt referencing syntax; write the prompt naturally and your text is sent verbatim:

const result = await generateImage({
  adapter: grokImage("grok-imagine-image"),
  prompt: [
    {
      type: "text",
      content: "Render the product in the style of the second image",
    },
    {
      type: "image",
      source: { type: "url", value: "https://example.com/product.png" },
    },
    {
      type: "image",
      source: { type: "url", value: "https://example.com/style.png" },
    },
  ],
});

URL sources are fetched by xAI's servers, so they must be publicly reachable; use a data source for private images. grok-2-image-1212 is text-to-image only — image prompt parts are a compile-time type error and throw at runtime.

Text-to-Speech

Generate speech with Grok TTS:

import { generateSpeech } from "@tanstack/ai";
import { grokSpeech } from "@tanstack/ai-grok";

const result = await generateSpeech({
  adapter: grokSpeech("grok-tts"),
  text: "Hello from Grok!",
  voice: "default",
  format: "mp3",
});

console.log(result.audio); // Base64-encoded audio

Transcription

Transcribe audio with Grok STT:

import { generateTranscription } from "@tanstack/ai";
import { grokTranscription } from "@tanstack/ai-grok";

const result = await generateTranscription({
  adapter: grokTranscription("grok-stt"),
  audio: audioFile,
});

console.log(result.text);

Realtime Voice

Grok also exposes a Realtime voice adapter (grokRealtime) and a token issuer (grokRealtimeToken) for low-latency voice conversations. See Realtime Voice Chat for the end-to-end flow.

Environment Variables

Set your API key in environment variables:

shell

XAI_API_KEY=xai-...

Implementation Notes

Why Chat Completions API (Not Responses API)

The Grok adapter uses xAI's Chat Completions API (/v1/chat/completions) rather than the Responses API (/v1/responses). This is an intentional architectural decision:

User-Defined Tools: The Chat Completions API supports user-defined function tools, which is essential for TanStack AI's tool calling functionality. The Responses API only supports xAI's server-side tools (web search, X search, code execution).
Full Tool Calling Support: With Chat Completions, you can define custom tools with Zod schemas that run in your application. The Responses API restricts you to xAI's built-in tools only.
Streaming Compatibility: The streaming event format differs significantly between the two APIs. Chat Completions uses delta.tool_calls with argument accumulation, while Responses API uses response.output_item.added and response.function_call_arguments.done.
OpenAI SDK Compatibility: xAI's Chat Completions API is fully compatible with the OpenAI SDK, making integration straightforward while maintaining full feature parity for tool calling.
If you need xAI's server-side tools (web search, X/Twitter search, code execution), you would need to use the Responses API directly. However, for most use cases requiring custom tool definitions, the Chat Completions API is the correct choice.

API Reference

grokText(model, config?)

Creates a Grok text adapter using environment variables.

Parameters:

model - The model name (e.g., 'grok-4', 'grok-4-1-fast-reasoning')
config.baseURL? - Custom base URL (optional)
Returns: A Grok text adapter instance.

createGrokText(model, apiKey, config?)

Creates a Grok text adapter with an explicit API key.

Parameters:

model - The model name
apiKey - Your xAI API key
config.baseURL? - Custom base URL (optional)
Returns: A Grok text adapter instance.

grokSummarize(model, config?)

Creates a Grok summarization adapter using environment variables.

Returns: A Grok summarize adapter instance.

createGrokSummarize(model, apiKey, config?)

Creates a Grok summarization adapter with an explicit API key.

Returns: A Grok summarize adapter instance.

grokImage(model, config?) / createGrokImage(model, apiKey, config?)

Creates a Grok image generation adapter.

grokSpeech(model, config?) / createGrokSpeech(model, apiKey, config?)

Creates a Grok text-to-speech adapter.

grokTranscription(model, config?) / createGrokTranscription(model, apiKey, config?)

Creates a Grok speech-to-text adapter.

grokRealtime(...) / grokRealtimeToken(...)

Realtime voice adapter and token issuer. See Realtime Voice Chat for usage.

Limitations

Responses API Tools: Server-side tools (web search, X search, code execution) are not supported through this adapter. Use the Chat Completions API with custom tools instead.