nRouter SDK for Rust
One API key for models across six provider clouds.
TypeSafe Jev System One
demo/jev_system_one.rs sends a standard
chat-completions request to typesafe/jev and prints the decision plus normal
nRouter metadata. See the cross-SDK JEV Examples
index for prerequisites and feature limits.
Installation
Add nrouter to your Cargo.toml:
[]
= "3.1.5"
= { = "1", = ["macros", "rt-multi-thread"] }
Or for development from a local repository checkout:
[]
= { = "../nrouter-sdk/sdks/rust" }
= { = "1", = ["macros", "rt-multi-thread"] }
Authentication & Setup
Set your API key in the environment:
Two entry points, on purpose
nrouter::client() returns an [async-openai] client pointed at the
gateway, so every OpenAI-shaped call you already write keeps working:
use ;
let client = client?; // reads NROUTER_API_KEY
let request = default
.model
.messages
.build?;
let response = client.chat.create.await?;
nrouter::http::Client is a native client that hands back the x-nr-*
metadata. async-openai discards the raw response, so per-request cost, token
counts and cache outcome are unreachable through it — that is the whole reason
this second path exists:
Custom gateway URLs must use HTTPS. Plain HTTP is accepted only for
localhost or a loopback IP so local development remains possible without
ever sending an API key unencrypted to a remote host.
use json;
let client = from_env?;
let out = client.chat_completions.await?;
// Branch on the status, never on `cost` being None-ish. An unpriced model
// reports cost == None, and rendering that as 0.0 reports a free request —
// which no enabled model is.
match out.meta.cost
ResponseMeta carries every x-nr-* header the gateway emits, named in
snake_case — x-nr-request-cost becomes cost and
x-nr-cache-read-tokens becomes cache_read_tokens. The authoritative set is
spec/gateway-response-headers.json,
derived from the gateway and held against this SDK by
conformance/check_conformance.py. This page does not restate it: a copied
list of a set that grows is a list that goes stale, and under the word "every"
it becomes a false claim of exhaustiveness rather than a stale number.
Streaming
The native client incrementally parses SSE on all four text wires. delta is
portable across OpenAI and Anthropic frames; raw preserves the complete
provider-native JSON. Dropping the stream drops the response body, cancelling
unread generation:
let mut stream = client.messages_stream.await?;
while let Some = stream.next.await?
println!;
chat_completions_stream, completions_stream, messages_stream, and
responses_stream clone the request body and force stream: true. An in-band
output-guardrail event returns NRouterError::GuardrailBlocked; a bare EOF is
a retryable transport failure, never a clean completion.
Errors
NRouterError variants are chosen from the gateway's stable code — not the
HTTP status alone, which cannot separate multiple 400, 402 or 429 conditions.
match client.chat_completions.await
| Variant | Code(s) | HTTP |
|---|---|---|
Request |
invalid_request, input_too_large, max_output_tokens_too_large, fallback_not_allowed, guardrail_not_found, image_input_unsupported, pot_route_feature_unsupported, cost_band_unsatisfiable |
400 |
GuardrailBlocked |
guardrail_blocked |
400 |
Authentication |
invalid_api_key, byok_credential_rejected |
401 |
Credit |
insufficient_credits, plan_allowance_exhausted, plan_required, insufficient_promo_credit, insufficient_hack_credit, byok_plan_required |
402 |
NotFound |
model_not_found |
404 |
RateLimit |
rate_limit_exceeded, tpm_limit_exceeded, pot_spend_limit_exceeded, byok_fair_use_exceeded |
429 |
Service |
credit_check_failed, service_unavailable |
503 |
Other |
model_denied_by_org, model_denied_by_team, model_denied_by_key, byok_credential_unavailable, anything newer than this SDK |
403 / 409 / — |
Transport |
never reached the gateway | — |
is_retryable() is true only for RateLimit, Service and Transport. Every
other variant names something permanent, where a retry burns quota and cannot
change the answer.
ErrorBody::limit_source names WHICH ceiling refused a 429. It is None when
the gateway could not attribute the refusal, and this SDK does not guess —
sending a customer to raise the wrong limit is worse than saying nothing.
Configuration
let client = new?
.with_base_url
.with_http_client; // proxy, timeouts, pooling
Endpoints
All 15 gateway operations have named buffered helpers: chat_completions, completions,
embeddings, images_generations, messages, count_tokens, responses,
models, model, create_video, retrieve_video, download_video_content,
audio_speech, audio_transcriptions, and audio_translations. post, get,
bytes, multipart, and stream remain available as escape hatches.
Not JSON: audio_transcriptions and audio_translations send multipart/form-data
(the gateway requires a binary file part, so the JSON helpers cannot reach them);
audio_speech() and download_video_content() return raw bytes plus metadata;
bytes(method, path, body) remains available for other non-JSON responses. The
JSON helpers refuse a non-JSON response rather than handing back an empty body
for a request you were billed for.
Build and test
MSRV 1.88 — the effective floor of the dependency graph (icu_* via reqwest's
TLS stack declare 1.88). Derive it rather than trusting this line:
|
&)