nRouter SDK for Rust
One API key for models across six provider clouds.
Source preview: the crate is not on crates.io. Use the repository checkout as a path dependency until the first registry release.
[]
= { = "../nrouter-sdk/sdks/rust" }
= { = "1", = ["macros", "rt-multi-thread"] }
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 all thirteen x-nr-* headers: request_id, cost,
cost_status, model, input_tokens, output_tokens, total_tokens,
cache_read_tokens, cache_write_tokens, limit_source, auth_reason,
response_cache, response_cache_age.
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, which cannot separate the two 400s or the two 429s.
match client.chat_completions.await
| Variant | Code(s) | HTTP |
|---|---|---|
Request |
invalid_request |
400 |
GuardrailBlocked |
guardrail_blocked |
400 |
Authentication |
invalid_api_key |
401 |
Credit |
insufficient_credits |
402 |
NotFound |
model_not_found |
404 |
RateLimit |
rate_limit_exceeded, tpm_limit_exceeded |
429 |
Service |
credit_check_failed, service_unavailable |
503 |
Other |
anything newer than this SDK | — |
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:
|