SDKsRust SDK
Rust SDK
The official nRouter Rust SDK providing standard async-openai integration and a native client for x-nr-* metadata parsing, streaming, and cost tracking.
The official nRouter Rust SDK provides asynchronous Tokio-native bindings for the unified AI gateway at https://api.nrouter.ai/v1. It features drop-in async-openai integration and a native client with NROUTER_API_KEY authentication, live x-nr-* cost tracking, and zero-allocation SSE streaming.
Installation
Add dependencies to Cargo.toml:
[dependencies]
nrouter = "3.1.2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
serde_json = "1"
async-openai = { version = "0.41.3", features = ["full"] }Set your environment variable:
export NROUTER_API_KEY="sk-nrouter-xxxxxxxxxxxx"Chat Completion
Use async-openai or the native client targeting https://api.nrouter.ai/v1:
use async_openai::types::chat::{ChatCompletionRequestUserMessageArgs, CreateChatCompletionRequestArgs};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = nrouter::client()?;
let request = CreateChatCompletionRequestArgs::default()
.model("gpt-5.4-mini")
.messages(vec![ChatCompletionRequestUserMessageArgs::default().content("Hello!").build()?.into()])
.build()?;
let response = client.chat().create(request).await?;
println!("{}", response.choices[0].message.content.as_deref().unwrap_or_default());
let http_client = nrouter::http::Client::from_env()?;
let out = http_client.chat_completions(&serde_json::json!({"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "Hello!"}]})).await?;
println!("Cost: {:?} ({:?})", out.meta.cost, out.meta.cost_status);
Ok(())
}SSE Streaming
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = nrouter::http::Client::from_env()?;
let mut stream = client.messages_stream(&json!({
"model": "claude-haiku-4-5-20251001",
"max_tokens": 256,
"messages": [{"role": "user", "content": "Write a haiku."}]
})).await?;
while let Some(chunk) = stream.next().await? {
print!("{}", chunk.delta);
}
println!();
Ok(())
}Error Handling
Gateway refusals map to NRouterError variants:
| Variant | HTTP Status | Description |
|---|---|---|
GuardrailBlocked | 400 | Blocked by configured guardrail |
Authentication | 401 | Invalid or revoked NROUTER_API_KEY |
Credit | 402 | Account balance or key budget ceiling reached |
RateLimit | 429 | RPM or TPM rate limit exceeded |
Service | 503 | Gateway or upstream provider error |
For fallbacks and routing options, see Router Settings and Per-Request Options.
Next Steps
- Go SDK Guide — Go client documentation
- Python SDK Guide — Official Python SDK
- Chat Completions API — HTTP endpoint specifications
Was this page helpful?