Class XAIClient

xAI API client.

Example

const client = new XAIClient({
  apiKey: process.env.API_KEY_XAI!,
  defaultModel: 'grok-3',
});

// Chat
const text = await client.chatSimple([
  { role: 'user', content: 'Hello!' }
]);

// Stream
for await (const delta of client.streamContent([
  { role: 'user', content: 'Tell me a story' }
])) {
  process.stdout.write(delta.content);
}

// Web search (xAI-specific)
const response = await client.chatWithWebSearch([
  { role: 'user', content: 'What happened in the news today?' }
]);

Constructors

constructor

new XAIClient(config: XAIClientConfig): XAIClient
Parameters
- config: XAIClientConfig
Returns XAIClient
- Defined in providers/xai/client.ts:140

Properties

cosineSimilarity

cosineSimilarity: (a: number[], b: number[]) => number = cosineSimilarity

Calculate cosine similarity between two vectors.

Type Declaration

- (a: number[], b: number[]): number
- Calculate cosine similarity between two vectors.
  Parameters
  - a: number[]
    First vector
  - b: number[]
    Second vector
  Returns number
  Similarity score between -1 and 1

findSimilar

findSimilar: <T>(
    query: number[],
    corpus: { embedding: number[]; item: T }[],
    topK?: number,
) => { item: T; score: number }[] = findSimilar

Find similar items from a corpus.

Type Declaration

- <T>(
      query: number[],
      corpus: { embedding: number[]; item: T }[],
      topK?: number,
  ): { item: T; score: number }[]
- Find the most similar items from a corpus.
  Type Parameters
  - T
  Parameters
  - query: number[]
    Query embedding
  - corpus: { embedding: number[]; item: T }[]
    Array of items with embeddings
  - topK: number = 5
    Number of results to return
  Returns { item: T; score: number }[]
  Top K most similar items with scores

Methods

chat

chat(
messages: Message[],
options?: Partial<ChatOptions>,
): Promise<ChatCompletion>
Create a chat completion.
Parameters
- messages: Message[]
- Optionaloptions: Partial<ChatOptions>
Returns Promise<ChatCompletion>
- Defined in providers/xai/client.ts:178

chatSimple

chatSimple(messages: Message[], options?: Partial<ChatOptions>): Promise<string>
Create a chat completion and return just the text content.
Parameters
- messages: Message[]
- Optionaloptions: Partial<ChatOptions>
Returns Promise<string>
- Defined in providers/xai/client.ts:185

chatWithTools

chatWithTools(
    messages: Message[],
    tools: Tool[],
    options?: Partial<ChatOptions> & {
        toolChoice?: ToolChoice;
        parallelToolCalls?: boolean;
    },
): Promise<
    | { type: "content"; content: string; usage: Usage }
    | { type: "tool_calls"; toolCalls: ToolCall[]; usage: Usage },
>
Chat with tools/function calling.
Parameters
- messages: Message[]
- tools: Tool[]
- Optionaloptions: Partial<ChatOptions> & { toolChoice?: ToolChoice; parallelToolCalls?: boolean }
Returns Promise<
| { type: "content"; content: string; usage: Usage }
| { type: "tool_calls"; toolCalls: ToolCall[]; usage: Usage },
>
- Defined in providers/xai/client.ts:192

chatWithWebSearch

chatWithWebSearch(
messages: Message[],
options?: Partial<ChatOptions>,
): Promise<ChatCompletion>
Chat with web search enabled (xAI-specific).
Parameters
- messages: Message[]
- Optionaloptions: Partial<ChatOptions>
Returns Promise<ChatCompletion>
- Defined in providers/xai/client.ts:211

chatStructured

chatStructured<T>(
    messages: Message[],
    schema: {
        name: string;
        description?: string;
        schema: Record<string, unknown>;
        strict?: boolean;
    },
    options?: Partial<ChatOptions>,
): Promise<T>
Chat with structured JSON output.
Type Parameters
- T
Parameters
- messages: Message[]
- schema: {
      name: string;
      description?: string;
      schema: Record<string, unknown>;
      strict?: boolean;
  }
- Optionaloptions: Partial<ChatOptions>
Returns Promise<T>
- Defined in providers/xai/client.ts:221

stream

stream(
messages: Message[],
options?: Partial<ChatStreamOptions>,
): AsyncGenerator<ChatCompletionChunk, void, undefined>
Stream chat completion chunks.
Parameters
- messages: Message[]
- Optionaloptions: Partial<ChatStreamOptions>
Returns AsyncGenerator<ChatCompletionChunk, void, undefined>
- Defined in providers/xai/client.ts:241

streamContent

streamContent(
messages: Message[],
options?: Partial<ChatStreamOptions>,
): AsyncGenerator<StreamDelta, void, undefined>
Stream content deltas.
Parameters
- messages: Message[]
- Optionaloptions: Partial<ChatStreamOptions>
Returns AsyncGenerator<StreamDelta, void, undefined>
- Defined in providers/xai/client.ts:255

streamAccumulate

streamAccumulate(
    messages: Message[],
    options?: Partial<ChatStreamOptions>,
    onDelta?: (delta: string) => void,
): Promise<
    {
        content: string;
        toolCalls: {
            id: string;
            type: "function";
            function: { name: string; arguments: string };
        }[];
        finishReason: string
        | null;
        usage: Usage | null;
        model: string;
        id: string;
    },
>
Stream and accumulate full response.
Parameters
- messages: Message[]
- Optionaloptions: Partial<ChatStreamOptions>
- OptionalonDelta: (delta: string) => void
Returns Promise<
    {
        content: string;
        toolCalls: {
            id: string;
            type: "function";
            function: { name: string; arguments: string };
        }[];
        finishReason: string
        | null;
        usage: Usage | null;
        model: string;
        id: string;
    },
>
- Defined in providers/xai/client.ts:266

streamReadable

streamReadable(
messages: Message[],
options?: Partial<ChatStreamOptions>,
): ReadableStream<string>
Create a readable stream of content.
Parameters
- messages: Message[]
- Optionaloptions: Partial<ChatStreamOptions>
Returns ReadableStream<string>
- Defined in providers/xai/client.ts:285

embed

embed(
input: string | string[],
options?: Partial<EmbeddingOptions>,
): Promise<EmbeddingResponse>
Generate embeddings for text input.
Parameters
- input: string | string[]
- Optionaloptions: Partial<EmbeddingOptions>
Returns Promise<EmbeddingResponse>
- Defined in providers/xai/client.ts:303

embedOne

embedOne(text: string, options?: Partial<EmbeddingOptions>): Promise<number[]>
Generate embedding for a single text.
Parameters
- text: string
- Optionaloptions: Partial<EmbeddingOptions>
Returns Promise<number[]>
- Defined in providers/xai/client.ts:317

embedMany

embedMany(
texts: string[],
options?: Partial<EmbeddingOptions>,
): Promise<number[][]>
Generate embeddings for multiple texts.
Parameters
- texts: string[]
- Optionaloptions: Partial<EmbeddingOptions>
Returns Promise<number[][]>
- Defined in providers/xai/client.ts:328

generateImage

generateImage(
prompt: string,
options?: Partial<ImageGenerationOptions>,
): Promise<ImageGenerationResponse>
Generate images from a prompt.
Parameters
- prompt: string
- Optionaloptions: Partial<ImageGenerationOptions>
Returns Promise<ImageGenerationResponse>
- Defined in providers/xai/client.ts:351

generateImageUrl

generateImageUrl(
prompt: string,
options?: Partial<ImageGenerationOptions>,
): Promise<string>
Generate a single image and return its URL.
Parameters
- prompt: string
- Optionaloptions: Partial<ImageGenerationOptions>
Returns Promise<string>
- Defined in providers/xai/client.ts:361

generateImageBase64

generateImageBase64(
prompt: string,
options?: Partial<ImageGenerationOptions>,
): Promise<string>
Generate a single image and return its base64 data.
Parameters
- prompt: string
- Optionaloptions: Partial<ImageGenerationOptions>
Returns Promise<string>
- Defined in providers/xai/client.ts:371

generateImages

generateImages(
    prompt: string,
    count: number,
    options?: Partial<ImageGenerationOptions>,
): Promise<ImageData[]>
Generate multiple images from a single prompt.
Parameters
- prompt: string
- count: number
- Optionaloptions: Partial<ImageGenerationOptions>
Returns Promise<ImageData[]>
- Defined in providers/xai/client.ts:381

generateImageWithPrompt

generateImageWithPrompt(
prompt: string,
options?: Partial<ImageGenerationOptions>,
): Promise<{ url: string; revisedPrompt: string }>
Generate image and return both URL and revised prompt.
Parameters
- prompt: string
- Optionaloptions: Partial<ImageGenerationOptions>
Returns Promise<{ url: string; revisedPrompt: string }>
- Defined in providers/xai/client.ts:392

editImage

editImage(
    prompt: string,
    imageUrl: string,
    options?: Partial<ImageEditOptions>,
): Promise<ImageGenerationResponse>
Edit an existing image with natural language instructions.
Parameters
- prompt: string
- imageUrl: string
- Optionaloptions: Partial<ImageEditOptions>
Returns Promise<ImageGenerationResponse>
- Defined in providers/xai/client.ts:414

editImageUrl

editImageUrl(
    prompt: string,
    imageUrl: string,
    options?: Partial<ImageEditOptions>,
): Promise<string>
Edit an image and return just the URL.
Parameters
- prompt: string
- imageUrl: string
- Optionaloptions: Partial<ImageEditOptions>
Returns Promise<string>
- Defined in providers/xai/client.ts:425

editImageBase64

editImageBase64(
    prompt: string,
    imageUrl: string,
    options?: Partial<ImageEditOptions>,
): Promise<string>
Edit an image and return base64 data.
Parameters
- prompt: string
- imageUrl: string
- Optionaloptions: Partial<ImageEditOptions>
Returns Promise<string>
- Defined in providers/xai/client.ts:436

editMultipleImages

editMultipleImages(
    prompt: string,
    imageUrls: string[],
    options?: Partial<ImageEditOptions>,
): Promise<ImageGenerationResponse>
Edit with multiple source images (up to 3).
Parameters
- prompt: string
- imageUrls: string[]
- Optionaloptions: Partial<ImageEditOptions>
Returns Promise<ImageGenerationResponse>
- Defined in providers/xai/client.ts:447

listModels

listModels(): Promise<ModelsResponse>
List all models (OpenAI-compatible).

Returns Promise<ModelsResponse>
- Defined in providers/xai/client.ts:462

getModel

getModel(modelId: string): Promise<Model>
Get a specific model (OpenAI-compatible).
Parameters
- modelId: string
Returns Promise<Model>
- Defined in providers/xai/client.ts:469

modelExists

modelExists(modelId: string): Promise<boolean>
Check if a model exists.
Parameters
- modelId: string
Returns Promise<boolean>
- Defined in providers/xai/client.ts:476

listLanguageModels

listLanguageModels(): Promise<LanguageModelsResponse>
List language models with detailed information (xAI-specific).

Returns Promise<LanguageModelsResponse>
- Defined in providers/xai/client.ts:483

getLanguageModel

getLanguageModel(modelId: string): Promise<LanguageModel>
Get a specific language model (xAI-specific).
Parameters
- modelId: string
Returns Promise<LanguageModel>
- Defined in providers/xai/client.ts:490

listImageGenerationModels

listImageGenerationModels(): Promise<ImageGenerationModelsResponse>
List image generation models (xAI-specific).

Returns Promise<ImageGenerationModelsResponse>
- Defined in providers/xai/client.ts:497

getImageGenerationModel

getImageGenerationModel(modelId: string): Promise<ImageGenerationModel>
Get a specific image generation model (xAI-specific).
Parameters
- modelId: string
Returns Promise<ImageGenerationModel>
- Defined in providers/xai/client.ts:504

generateVideo

generateVideo(
    prompt: string,
    options?: Partial<VideoGenerationOptions>,
    pollingOptions?: VideoPollingOptions,
): Promise<VideoGenerationResult>
Generate a video and wait for completion (handles polling automatically).

Video generation is asynchronous and can take several minutes. This method handles polling automatically.
Parameters
- prompt: string
- Optionaloptions: Partial<VideoGenerationOptions>
- OptionalpollingOptions: VideoPollingOptions
Returns Promise<VideoGenerationResult>
- Defined in providers/xai/client.ts:526

generateVideoUrl

generateVideoUrl(
    prompt: string,
    options?: Partial<VideoGenerationOptions>,
    pollingOptions?: VideoPollingOptions,
): Promise<string>
Generate a video and return just the URL.
Parameters
- prompt: string
- Optionaloptions: Partial<VideoGenerationOptions>
- OptionalpollingOptions: VideoPollingOptions
Returns Promise<string>
- Defined in providers/xai/client.ts:537

generateVideoFromImage

generateVideoFromImage(
    prompt: string,
    imageUrl: string,
    options?: Partial<VideoGenerationOptions>,
    pollingOptions?: VideoPollingOptions,
): Promise<VideoGenerationResult>
Generate a video from a still image (image-to-video).
Parameters
- prompt: string
- imageUrl: string
- Optionaloptions: Partial<VideoGenerationOptions>
- OptionalpollingOptions: VideoPollingOptions
Returns Promise<VideoGenerationResult>
- Defined in providers/xai/client.ts:548

editVideo

editVideo(
    prompt: string,
    videoUrl: string,
    options?: Partial<VideoGenerationOptions>,
    pollingOptions?: VideoPollingOptions,
): Promise<VideoGenerationResult>
Edit an existing video with natural language instructions.
Parameters
- prompt: string
- videoUrl: string
- Optionaloptions: Partial<VideoGenerationOptions>
- OptionalpollingOptions: VideoPollingOptions
Returns Promise<VideoGenerationResult>
- Defined in providers/xai/client.ts:560

startVideoGeneration

startVideoGeneration(
prompt: string,
options?: Partial<VideoGenerationOptions>,
): Promise<{ requestId: string }>
Start a video generation request without waiting (manual polling).

Use getVideoStatus to poll for results.
Parameters
- prompt: string
- Optionaloptions: Partial<VideoGenerationOptions>
Returns Promise<{ requestId: string }>
- Defined in providers/xai/client.ts:574

getVideoStatus

getVideoStatus(requestId: string): Promise<VideoGenerationStatusResponse>
Check the status of a video generation request.
Parameters
- requestId: string
Returns Promise<VideoGenerationStatusResponse>
- Defined in providers/xai/client.ts:584

Class XAIClient

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns XAIClient

Properties

cosineSimilarity

Type Declaration

Parameters

Returns number

findSimilar

Type Declaration

Type Parameters

Parameters

Returns { item: T; score: number }[]

Methods

chat

Parameters

Returns Promise<ChatCompletion>

chatSimple

Parameters

Returns Promise<string>

chatWithTools

Parameters

Returns Promise< | { type: "content"; content: string; usage: Usage } | { type: "tool_calls"; toolCalls: ToolCall[]; usage: Usage },>

chatWithWebSearch

Parameters

Returns Promise<ChatCompletion>

chatStructured

Type Parameters

Parameters

Returns Promise<T>

stream

Parameters

Returns AsyncGenerator<ChatCompletionChunk, void, undefined>

streamContent

Parameters

Returns AsyncGenerator<StreamDelta, void, undefined>

streamAccumulate

Parameters

Returns Promise< { content: string; toolCalls: { id: string; type: "function"; function: { name: string; arguments: string }; }[]; finishReason: string | null; usage: Usage | null; model: string; id: string; },>

streamReadable

Parameters

Returns ReadableStream<string>

embed

Parameters

Returns Promise<EmbeddingResponse>

embedOne

Parameters

Returns Promise<number[]>

embedMany

Parameters

Returns Promise<number[][]>

generateImage

Parameters

Returns Promise<ImageGenerationResponse>

generateImageUrl

Parameters

Returns Promise<string>

generateImageBase64

Parameters

Returns Promise<string>

generateImages

Parameters

Returns Promise<ImageData[]>

generateImageWithPrompt

Parameters

Returns Promise<{ url: string; revisedPrompt: string }>

editImage

Parameters

Returns Promise<ImageGenerationResponse>

editImageUrl

Parameters

Returns Promise<string>

editImageBase64

Returns Promise<
| { type: "content"; content: string; usage: Usage }
| { type: "tool_calls"; toolCalls: ToolCall[]; usage: Usage },
>

Returns Promise<
{
content: string;
toolCalls: {
id: string;
type: "function";
function: { name: string; arguments: string };
}[];
finishReason: string
| null;
usage: Usage | null;
model: string;
id: string;
},
>