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.
- 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
- Rust 1.88+ installed
- xAI inference API key (
XAI_API_KEY) for chat, models, embeddings, etc. - For billing: a management API key (
XAI_MANAGEMENT_API_KEY) and team UUID (XAI_TEAM_ID) from the xAI console — billing useshttps://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).
Add to your Cargo.toml:
[dependencies]
xai-sdk = "0.15"
tokio = { version = "1.0", features = ["full"] }
anyhow = "1.0"-
Set your inference API key:
export XAI_API_KEY="your-api-key-here"
-
Run the authentication info example:
cargo run --example auth_info
-
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
-
Run the multi-client example (demonstrates using multiple services with shared channel):
cargo run --example multi_client
-
Run the interceptor composition example:
cargo run --example interceptor_compose
-
Run the tool calls example:
cargo run --example tool_calls
-
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
The SDK provides clients for all xAI services:
get_completion- Get chat completionget_completion_chunk- Stream chat completion in chunksstart_deferred_completion- Start deferred chat completionget_deferred_completion- Retrieve deferred completionget_stored_completion- Get stored chat completiondelete_stored_completion- Delete stored chat completion
list_language_models- List available language modelslist_embedding_models- List embedding modelslist_image_generation_models- List image generation models
embed- Generate embeddings from text or images
generate_image- Create images from text prompts
generate_video- Create videos with deferred processingget_deferred_video- Retrieve generated videos
get_api_key_info- Get API key information
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 teamget_billing_info- Get billing information for a teamlist_payment_methods- List payment methods on fileset_default_payment_method- Set default payment methodget_amount_to_pay- Preview current billing period amountanalyze_billing_items- Analyze historical billing usagelist_invoices- List invoices for a teamlist_prepaid_balance_changes- List prepaid credit balance changestop_up_or_get_existing_pending_change- Top up prepaid creditsget_spending_limits- Get spending limitsset_soft_spending_limit- Set soft spending limit
upload_file- Upload files via streaming chunkslist_files- List uploaded files with pagination/sortingretrieve_file- Retrieve file metadata by IDdelete_file- Delete a file by IDretrieve_file_content- Stream file content (original bytes or extracted text)
create_batch- Create a new batch for asynchronous processingget_batch- Retrieve information about a specific batchlist_batches- List all batches owned by the teamcancel_batch- Cancel processing of all requests in a batchadd_batch_requests- Add completion requests to an existing batchlist_batch_request_metadata- List metadata for individual requests in a batchlist_batch_results- List processing results for a batchget_batch_request_result- Retrieve the result of a specific batch request
The SDK is organized into focused modules, each providing easy client creation:
auth- Authentication servicesbilling- Billing and payment managementchat- Chat completions and streamingdocuments- Document processingembed- Text and image embeddingsfiles- File upload and managementimage- Image generationmodels- Model listing and informationtokenize- Text tokenizationvideo- Video generation with deferred processingbatch- Batch processing and management
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(())
}The SDK provides powerful utilities for working with streaming responses:
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 chunkReasoningStart/ReasoningToken/ReasoningComplete- Reasoning phase per outputContentStart/ContentToken/ContentComplete- Content phase per outputInlineCitations- Inline citations in a deltaClientToolCalls/ServerToolCalls- Tool calls in a deltaCitations- Source URLs from the final chunkUsage- Token usage from the final chunkComplete- Successful end of stream (not emitted on errors)Error(Status)- gRPC failure beforeprocessreturnsErr
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,
_ => {}
}
}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 |
chat::stream::process(stream, sink)- Emit events and collect raw chunkschat::stream::collect(stream)- Chunks only (processwithxai_sdk::export::futures::sink::drain())chat::stream::assemble- Convert collected chunks into a complete response
The SDK provides a flexible interceptor system for customizing request handling:
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?;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.
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 intokio::spawnand 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...
});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
- TLS Encryption: Automatic HTTPS with certificate validation
- Authentication: Bearer token support for API key authentication
- Secure by Default: No manual TLS configuration required
Comprehensive error handling for:
- Connection errors and timeouts
- Authentication failures
- API rate limiting
- Invalid parameters
- Network issues
This SDK is built using:
- Protocol Buffers: Auto-generated Rust types from xAI's
.protodefinitions - 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.
See CHANGELOG.md for a detailed list of changes and new features.
This project is licensed under the MIT License.