Skip to content
0xC0DE666Public

About

A Rust SDK for xAI's API, providing type-safe gRPC clients for all xAI services including Grok language models, embeddings, image generation, and more.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

292 Commits

Folders and files

Repository files navigation

xAI SDK

A Rust SDK for xAI's API, providing type-safe gRPC clients for all xAI services including Grok language models, embeddings, image generation, and more.

Note

This is an unofficial SDK and is not affiliated with or endorsed by xAI.

Warning

This project is in early development and is not production-ready. The API is subject to change without notice.

Features

  • Complete API Coverage: Full gRPC client implementation for all xAI services including chat completions, embeddings, image generation, video generation, batch processing, and billing management
  • Type Safety: Auto-generated Rust types from Protocol Buffers
  • Multiple Models: Support for all xAI language models (Grok-4, etc.)
  • Streaming Support: Real-time streaming for chat completions and text generation
  • Response Assembly: Convert streaming chunks into complete responses
  • Batch Processing: Asynchronous batch processing for large-scale requests
  • Secure: TLS encryption with automatic certificate validation

Quick Start

Prerequisites

  1. Rust 1.88+ installed
  2. xAI inference API key (XAI_API_KEY) for chat, models, embeddings, etc.
  3. For billing: a management API key (XAI_MANAGEMENT_API_KEY) and team UUID (XAI_TEAM_ID) from the xAI console — billing uses https://management-api.x.ai, not the inference host

Env var names are also exported as crate constants (xai_sdk::XAI_API_KEY, XAI_MANAGEMENT_API_KEY, XAI_TEAM_ID).

Installation

Add to your Cargo.toml:

[dependencies]
xai-sdk = "0.15"
tokio = { version = "1.0", features = ["full"] }
anyhow = "1.0"

Running the Examples

  1. Set your inference API key:

    export XAI_API_KEY="your-api-key-here"
  2. Run the authentication info example:

    cargo run --example auth_info
  3. Run the chat completion example (supports multiple modes):

    # Blocking completion
    cargo run --example chat -- --complete
    
    # Streaming completion
    cargo run --example chat -- --stream
    
    # Streaming with assembly
    cargo run --example chat -- --assemble
  4. Run the multi-client example (demonstrates using multiple services with shared channel):

    cargo run --example multi_client
  5. Run the interceptor composition example:

    cargo run --example interceptor_compose
  6. Run the tool calls example:

    cargo run --example tool_calls
  7. Run the billing example (management API):

    export XAI_MANAGEMENT_API_KEY="your-management-key"
    export XAI_TEAM_ID="your-team-uuid"
    cargo run --example billing

API Services

The SDK provides clients for all xAI services:

Chat Service

  • get_completion - Get chat completion
  • get_completion_chunk - Stream chat completion in chunks
  • start_deferred_completion - Start deferred chat completion
  • get_deferred_completion - Retrieve deferred completion
  • get_stored_completion - Get stored chat completion
  • delete_stored_completion - Delete stored chat completion

Models Service

  • list_language_models - List available language models
  • list_embedding_models - List embedding models
  • list_image_generation_models - List image generation models

Embed Service

  • embed - Generate embeddings from text or images

Image Service

  • generate_image - Create images from text prompts

Video Service

  • generate_video - Create videos with deferred processing
  • get_deferred_video - Retrieve generated videos

Auth Service

  • get_api_key_info - Get API key information

Billing Service (management API)

Billing uses https://management-api.x.ai via billing::client / shared::channel::management(). Authenticate with a management key; pass team_id on each request. Inference keys and the inference channel will not work here.

  • set_billing_info - Set billing information for a team
  • get_billing_info - Get billing information for a team
  • list_payment_methods - List payment methods on file
  • set_default_payment_method - Set default payment method
  • get_amount_to_pay - Preview current billing period amount
  • analyze_billing_items - Analyze historical billing usage
  • list_invoices - List invoices for a team
  • list_prepaid_balance_changes - List prepaid credit balance changes
  • top_up_or_get_existing_pending_change - Top up prepaid credits
  • get_spending_limits - Get spending limits
  • set_soft_spending_limit - Set soft spending limit

Files Service

  • upload_file - Upload files via streaming chunks
  • list_files - List uploaded files with pagination/sorting
  • retrieve_file - Retrieve file metadata by ID
  • delete_file - Delete a file by ID
  • retrieve_file_content - Stream file content (original bytes or extracted text)

Batch Service

  • create_batch - Create a new batch for asynchronous processing
  • get_batch - Retrieve information about a specific batch
  • list_batches - List all batches owned by the team
  • cancel_batch - Cancel processing of all requests in a batch
  • add_batch_requests - Add completion requests to an existing batch
  • list_batch_request_metadata - List metadata for individual requests in a batch
  • list_batch_results - List processing results for a batch
  • get_batch_request_result - Retrieve the result of a specific batch request

Client Modules

The SDK is organized into focused modules, each providing easy client creation:

Available Modules

  • auth - Authentication services
  • billing - Billing and payment management
  • chat - Chat completions and streaming
  • documents - Document processing
  • embed - Text and image embeddings
  • files - File upload and management
  • image - Image generation
  • models - Model listing and information
  • tokenize - Text tokenization
  • video - Video generation with deferred processing
  • batch - Batch processing and management

Complete Example

Here's a complete example showing multiple services using the modular architecture:

use anyhow::Context;
use std::env;
use xai_sdk::export::tonic::Request;
use xai_sdk::api::{
    Content, GetCompletionsRequest, GetModelRequest, Message, MessageRole, content,
};
use xai_sdk::{chat, models};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load API key for authentication
    let api_key = env::var(xai_sdk::XAI_API_KEY)
        .with_context(|| format!("{} environment variable must be set", xai_sdk::XAI_API_KEY))?;

    // Create authenticated clients for different services
    let mut models_client = models::client::new(api_key.clone()).await?;
    let mut chat_client = chat::client::new(api_key).await?;

    // List available models
    let models_request = Request::new(());
    let models_response = models_client.list_language_models(models_request).await?;
    println!("Available models: {:?}", models_response.into_inner().models);

    // Get details for a specific model
    let model_request = Request::new(GetModelRequest {
        name: "grok-4.20".to_string(),
    });
    let model_response = models_client.get_language_model(model_request).await?;
    println!("Model details: {:?}", model_response.into_inner());

    // Chat completion
    let message = Message {
        role: MessageRole::RoleUser.into(),
        content: vec![Content {
            content: Some(content::Content::Text("Explain Rust ownership".to_string())),
        }],
        ..Default::default()
    };
    let chat_request = Request::new(GetCompletionsRequest {
        model: "grok-4.20".to_string(),
        messages: vec![message],
        ..Default::default()
    });
    let chat_response = chat_client.get_completion(chat_request).await?;
    println!(
        "Chat response: {}",
        chat_response.into_inner().outputs[0]
            .message
            .as_ref()
            .unwrap()
            .content
    );

    Ok(())
}

Streaming Utilities

The SDK provides powerful utilities for working with streaming responses:

Event-driven streaming

chat::stream::process drives the stream and emits Events into any Sink<Event> (e.g. xai_sdk::export::futures::channel::mpsc::unbounded()). Match on events in your handler:

  • Chunk - Each raw gRPC chunk
  • ReasoningStart / ReasoningToken / ReasoningComplete - Reasoning phase per output
  • ContentStart / ContentToken / ContentComplete - Content phase per output
  • InlineCitations - Inline citations in a delta
  • ClientToolCalls / ServerToolCalls - Tool calls in a delta
  • Citations - Source URLs from the final chunk
  • Usage - Token usage from the final chunk
  • Complete - Successful end of stream (not emitted on errors)
  • Error(Status) - gRPC failure before process returns Err

OutputContext on phase/token events carries total_outputs, output_index, and reasoning_status / content_status (Init, Start, Pending, Complete).

use xai_sdk::export::futures::channel::mpsc;
use xai_sdk::export::futures::StreamExt;
use xai_sdk::chat::stream::{Event, process};

let (tx, mut rx) = mpsc::unbounded();
let chunks = process(stream, tx).await?;
while let Some(ev) = rx.next().await {
    match ev {
        Event::ContentToken(_, token) => print!("{token}"),
        Event::Complete => break,
        _ => {}
    }
}

export::futures (mailboxes, RPC, streaming)

Re-exported without adding futures to your Cargo.toml:

Path Use
export::futures::channel::mpsc Bounded mailboxes (channel(100)), Sender / Receiver, SendError, RecvError, TryRecvError
export::futures::channel::oneshot RPC reply channels (channel(), Sender, Receiver, Canceled)
export::futures::stream Stream trait, iter for test mocks
export::futures::{SinkExt, StreamExt} .send().await, .next().await, close receivers

Stream processing functions

  • chat::stream::process(stream, sink) - Emit events and collect raw chunks
  • chat::stream::collect(stream) - Chunks only (process with xai_sdk::export::futures::sink::drain())
  • chat::stream::assemble - Convert collected chunks into a complete response

Interceptors

The SDK provides a flexible interceptor system for customizing request handling:

Authentication Interceptor

The auth() function creates an interceptor that adds Bearer token authentication:

use xai_sdk::shared::interceptor::auth;

let interceptor = auth("your-api-key");
let client = chat::client::with_interceptor(interceptor).await?;

Composing Interceptors

Combine multiple interceptors using compose():

use xai_sdk::shared::interceptor::{auth, compose};

let interceptors: Vec<Box<dyn xai_sdk::export::tonic::service::Interceptor + Send + Sync>> = vec![
    Box::new(auth("your-api-key")),
    Box::new(|mut req| {
        req.metadata_mut().insert("x-custom-header", "value".parse().unwrap());
        Ok(req)
    }),
];
let composed = compose(interceptors);
let client = chat::client::with_interceptor(composed).await?;

Note: All interceptors must be Send + Sync to ensure thread safety when used in async contexts.

ClientInterceptor Type

All client functions return ClientInterceptor, a concrete type that can be:

  • Stored in structs
  • Used in trait implementations
  • Passed between functions without type erasure issues
  • Used across thread boundaries (Send + Sync) - safe to use in tokio::spawn and other async contexts

The ClientInterceptor can be created from any impl Interceptor + Send + Sync + 'static:

use xai_sdk::shared::interceptor::ClientInterceptor;

let interceptor = ClientInterceptor::new(|mut req| {
    // Custom logic
    Ok(req)
});

// Can be used in spawned tasks
tokio::spawn(async move {
    let client = chat::client::with_interceptor(interceptor).await?;
    // Use client...
});

Configuration

The SDK supports comprehensive configuration options:

  • Temperature: Controls randomness (0.0 to 2.0)
  • Top-p: Nucleus sampling parameter (0.0 to 1.0)
  • Max tokens: Maximum tokens to generate
  • Log probabilities: Enable detailed token probability logging
  • Multiple completions: Generate multiple responses per request
  • Stop sequences: Custom stop conditions
  • Frequency/Presence penalties: Control repetition and topic diversity

Security

  • TLS Encryption: Automatic HTTPS with certificate validation
  • Authentication: Bearer token support for API key authentication
  • Secure by Default: No manual TLS configuration required

Error Handling

Comprehensive error handling for:

  • Connection errors and timeouts
  • Authentication failures
  • API rate limiting
  • Invalid parameters
  • Network issues

Development

This SDK is built using:

  • Protocol Buffers: Auto-generated Rust types from xAI's .proto definitions
  • Tonic: Modern gRPC framework for Rust with async/await support
  • Prost: High-performance Protocol Buffer implementation

The code is generated from xAI's official Protocol Buffer definitions, ensuring compatibility and type safety.

Changelog

See CHANGELOG.md for a detailed list of changes and new features.

License

This project is licensed under the MIT License.

About

A Rust SDK for xAI's API, providing type-safe gRPC clients for all xAI services including Grok language models, embeddings, image generation, and more.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages