Browse documentation

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:

VariantHTTP StatusDescription
GuardrailBlocked400Blocked by configured guardrail
Authentication401Invalid or revoked NROUTER_API_KEY
Credit402Account balance or key budget ceiling reached
RateLimit429RPM or TPM rate limit exceeded
Service503Gateway or upstream provider error

For fallbacks and routing options, see Router Settings and Per-Request Options.

Next Steps

Was this page helpful?