@ai-sdk/xai

Instantiates xAI Grok language models (grok-beta, grok-vision-beta) through a standardized provider factory pattern that abstracts API authentication, request formatting, and response parsing. The provider integrates into the AI SDK's model registry, allowing developers to swap xAI models with other providers (OpenAI, Anthropic, etc.) without changing application code. Uses environment variable-based API key injection (XAI_API_KEY) and lazy-loads model configurations at runtime.

Streams token-by-token responses from xAI Grok models using the AI SDK's streamText() function, which internally manages HTTP streaming, chunk parsing, and event emission. Implements server-sent events (SSE) protocol handling with automatic reconnection and partial token buffering. Supports both text-only and vision-capable models with streaming output that can be consumed in real-time by frontend clients or piped to downstream processors.

Enables grok-vision-beta model to process images alongside text through the AI SDK's unified message format, which accepts image data as base64-encoded strings, URLs, or file paths. The provider automatically detects image content in messages and formats them according to xAI's vision API schema (image_url or base64 fields). Supports JPEG, PNG, WebP, and GIF formats with automatic MIME type detection and size validation before transmission.

Generates complete text responses from xAI Grok models using the AI SDK's generateText() function, which batches the entire response before returning. Supports optional structured output mode where responses are constrained to match a JSON schema or TypeScript type definition, enabling reliable extraction of structured data (JSON objects, arrays, enums) from model outputs. Uses xAI's native structured output API when available, with fallback to post-processing validation if not supported.

Enables xAI Grok models to call external functions and tools through the AI SDK's tool-calling abstraction, which defines tools as TypeScript functions with Zod schemas for parameter validation. The provider translates tool definitions into xAI's function-calling format, manages tool invocation requests from the model, and handles the request-response loop for multi-turn tool interactions. Supports both single-tool and multi-tool scenarios with automatic parameter marshaling and type validation.

Exposes xAI Grok model sampling parameters (temperature, top_p, top_k, frequency_penalty, presence_penalty) through the AI SDK's model configuration interface, allowing fine-grained control over response randomness and diversity. Parameters are validated and normalized to xAI's API ranges before transmission. Supports both per-request overrides and model-level defaults, enabling different sampling strategies for different use cases (deterministic extraction vs. creative generation).

Tracks token consumption for xAI Grok API calls through the AI SDK's usage metadata system, which returns input_tokens, output_tokens, and total_tokens after each generation. Enables cost estimation and quota management by exposing token counts at the function level. Supports both streaming and non-streaming modes, with token counts available immediately after generation completion.

Integrates xAI API errors into the AI SDK's error handling framework, which provides standardized error types (APIError, RateLimitError, AuthenticationError) and automatic retry logic with exponential backoff. Handles xAI-specific error codes (401 auth failures, 429 rate limits, 500 server errors) and maps them to AI SDK error types. Supports configurable retry policies (max attempts, backoff multiplier) at the model level.