openrouter-rs

openrouter-rs is a community-maintained Rust SDK for OpenRouter, with typed requests, streaming, tool calling, and access to OpenRouter's model, usage, and management APIs. A companion CLI is available for terminal and automation workflows.

[dependencies]
openrouter-rs = "0.19.0"
tokio = { version = "1", features = ["full"] }

Requires Rust 1.85+ and Tokio 1.x. To try it in a new project:

cargo new openrouter-quickstart
cd openrouter-quickstart

Add the dependencies above to Cargo.toml, then set your API key:

export OPENROUTER_API_KEY="your-openrouter-api-key"

Save this as src/main.rs and run cargo run:

use openrouter_rs::{
    OpenRouterClient,
    api::chat::{ChatCompletionRequest, Message},
    types::Role,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = OpenRouterClient::builder()
        .api_key(std::env::var("OPENROUTER_API_KEY")?)
        .build()?;

    let request = ChatCompletionRequest::builder()
        .model(std::env::var("OPENROUTER_MODEL").unwrap_or_else(|_| "openai/gpt-4o-mini".into()))
        .messages(vec![Message::new(
            Role::User,
            "Explain Rust ownership in plain English.",
        )])
        .max_tokens(256)
        .build()?;

    let response = client.chat().create(&request).await?;
    let choice = response.choices.first().ok_or("OpenRouter returned no choices")?;
    println!("{}", choice.content().unwrap_or(""));

    Ok(())
}

The SDK keeps setup intentionally narrow: configure runtime values on OpenRouterClient::builder(), then choose the final model on each request builder. File/profile config resolution belongs in the companion CLI or in your application layer, not in the SDK core.

Set OPENROUTER_MODEL to use another model ID available to your account. A successful request prints the model's reply. A missing key fails locally; for API authentication, credit, or model-availability errors, check your OpenRouter account and the returned error before retrying. API calls may consume credits.

These commands run from a checkout of this repository with OPENROUTER_API_KEY set:

Management-governed endpoints require OPENROUTER_MANAGEMENT_KEY; ordinary chat and credits requests use OPENROUTER_API_KEY. For a minimal HTTP server, see the Axum chat gateway.

• Domain-oriented clients: chat(), responses(), messages(), rerank(), audio().speech(), audio().transcriptions(), images(), videos(), files(), models(), management(), and opt-in legacy()
• Typed request/response models with builder-style ergonomics
• Tokio-native reqwest + rustls transport with no surf / curl dependency chain
• Streaming support for chat, responses, messages, and image generation, including a unified stream abstraction
• Typed tools, manual JSON-schema tools, OpenRouter server tools, and multimodal chat content
• Typed chat usage metadata for token counts, OpenRouter cost, provider cost breakdowns, and BYOK status
• Opt-in OpenRouter response metadata for chat, Responses API, and Anthropic-compatible Messages requests
• Discovery, rankings and benchmark datasets, task classifications, rerank, audio speech/transcription, image generation, video generation, provider-backed files, embeddings, API-key management, preset creation/readback/versioning, analytics, BYOK provider credentials, observability destinations, workspace management, SCIM group mappings, organization members/settings, end-user registrations, guardrails, activity, credits, and generation metadata/content coverage
• A companion CLI for profile resolution, discovery, management, and billing/usage workflows

Accepted endpoint coverage and live-test status are recorded separately in the endpoint matrix. See the changelog for release details and migration guide when upgrading, including the 0.19 speech input change.

Legacy text completions are opt-in:

[dependencies]
openrouter-rs = { version = "0.19.0", features = ["legacy-completions"] }

The canonical public surface is domain-oriented:

At runtime, the builder/client exposes the values the SDK directly consumes:

• base_url
• api_key
• management_key
• http_referer
• x_title
• app_categories
• http_client

Chat, Responses API, and Anthropic-compatible Messages request builders also expose experimental_metadata(OpenRouterExperimentalMetadata::Enabled) for OpenRouter's opt-in routing metadata response header.

openrouter-rs is not just a thin /chat/completions wrapper. The repo currently covers:

• chat completions, responses, and Anthropic-compatible messages
• rerank, audio speech generation, audio transcription, image generation, and video generation polling/content retrieval
• unified streaming across chat, responses, and messages
• manual tools, typed tools backed by schemars, and OpenRouter server tools such as openrouter:web_search and openrouter:datetime
• multimodal chat content, including image, audio, video, and file parts
• model discovery, provider discovery, app rankings, task classifications, unified benchmarks, embeddings, and ZDR endpoints
• typed generation metadata, model voice/benchmark/link metadata, workspace I/O logging controls, video callback URL support, and file upload/download workflows
• explicit chat prompt-cache breakpoints and static predictions, image provider routing controls, conditional model pricing, and image-only video generation requests
• assistant-message model annotations, transcription speaker labels, Anthropic compaction/dynamic-tool blocks, and round-tripped BYOK controls for guardrail/workspace budgets
• management-key workflows for keys, workspace-scoped keys, preset reads/writes, analytics, BYOK provider credentials, observability destinations, auth codes, organization members, workspaces, workspace budgets, workspace member listing/mutation, guardrails, guardrail content filters, workspace-scoped guardrails, and activity, plus API-key-authenticated credits and generation metadata/content endpoints

For deeper examples, prefer the runnable examples in examples/ over long README snippets.

OpenRouter server tools use the same ServerTool type across chat completions, Responses API, Anthropic-compatible Messages, and preset creation request bodies:

use openrouter_rs::{
    api::chat::{ChatCompletionRequest, Message},
    types::{Role, ServerTool},
};
use serde_json::json;

let request = ChatCompletionRequest::builder()
    .model("openai/gpt-5")
    .messages(vec![Message::new(Role::User, "Find current OpenRouter docs.")])
    .server_tool(ServerTool::web_search_with_parameters(json!({
        "max_results": 3
    })))
    .force_server_tool("openrouter:web_search")
    .build()?;

The repo includes runnable examples for the highest-value workflows:

Typical local usage:

export OPENROUTER_API_KEY=sk-or-v1-...

cargo run --example axum_chat_gateway
cargo run --example domain_chat_completion
cargo run --example stream_chat_completion
cargo run --example typed_tool_agent
cargo run --example typed_tool_calling
cargo run --example create_response
cargo run --example create_message
cargo run --example create_rerank
cargo run --example create_speech
cargo run --example create_transcription
cargo run --example create_image_generation
cargo run --example create_embedding
cargo run --example list_byok_keys
cargo run --example list_observability_destinations
cargo run --example custom_http_client

For shell and CI automation recipes built around the companion CLI, see docs/operations/cli-automation-workflows.md.

Retain the response message before appending tool results so signed/encrypted reasoning and other modeled assistant metadata survive the next client.chat().create(...) call:

if let Some(message) = choice.message() {
    messages.push(openrouter_rs::api::chat::Message::try_from(message)?);
}
// Then append Message::tool_response(...) for each tool call.

Choice::message() returns None for streaming and legacy text choices. The conversion preserves modeled response fields and rejects missing/unsupported roles; response content parts retain the SDK's existing text normalization. See examples/typed_tool_agent.rs. ReasoningDetail::summary and content() expose reasoning.summary blocks. For streaming tool loops, examples/stream_chat_with_tools.rs collects text/reasoning and retains reasoning-detail objects in arrival order before sending tool results.

Prompt-cache usage is available through response.usage → prompt_tokens_details → cached_tokens / cache_write_tokens. These are optional provider-reported counts; missing data is not evidence of a cache miss. The same usage type is used for streaming.

This workspace also contains crates/openrouter-cli, a companion CLI for profile resolution, discovery, management, and usage/billing workflows.

Examples:

cargo run -p openrouter-cli -- --help
cargo run -p openrouter-cli -- profile show
cargo run -p openrouter-cli -- models list --category programming
cargo run -p openrouter-cli -- keys list --include-disabled
cargo run -p openrouter-cli -- workspaces list --limit 20
cargo run -p openrouter-cli -- usage activity --date 2026-03-01

See crates/openrouter-cli/README.md for the full command surface and config/auth precedence rules. For copy-paste shell/CI recipes, see docs/operations/cli-automation-workflows.md.

• Community-maintained third-party SDK; not affiliated with OpenRouter
• Canonical docs and examples prefer the domain clients over older flat helpers
• Accepted endpoint coverage is tracked against the current OpenAPI snapshot, and the current baseline is reviewed, with 138 / 151 operations implemented at the SDK surface and 13 newer operations deferred
• Live integration coverage and gaps are published in docs/operations/official-endpoint-test-matrix.md
• Migration guidance for the 0.9.x -> 0.10.0 public-model future-proofing release, the 0.8.x -> 0.9.0 audio speech release, the 0.7.x -> 0.8.0 transport/error-surface release, and the archived 0.5.x -> 0.6.x naming guide lives in MIGRATION.md
• Legacy POST /completions support remains available behind the legacy-completions feature

Full migration guide: MIGRATION.md

• High-churn public SDK request, response, metadata, usage, pricing, discovery, streaming, and upstream taxonomy types are #[non_exhaustive]
• Replace affected struct literals with builders, constructors, helpers, or serde deserialization
• Add wildcard arms when matching affected public enums outside the crate
• Use constructors such as ResponseUsage::new(...), ToolCall::new(...), FunctionCall::new(...), and JsonSchemaConfig::new(...) for small helper/test fixtures
• This source-level break lands in 0.10.0

• client.tts().create(...) -> client.audio().speech().create(...)
• api::tts::TtsRequest -> api::audio::SpeechRequest
• api::tts::TtsResponseFormat -> api::audio::SpeechResponseFormat
• api::tts remains as a deprecated compatibility module, but new examples and docs use api::audio
• Newly added and high-churn public request/response structs use builder construction and may be marked #[non_exhaustive]; prefer request builders over struct literals

Full migration guide: MIGRATION.md

• OpenRouterError::HttpRequest(surf::Error) -> OpenRouterError::HttpRequest(HttpRequestError)
• ApiErrorContext.status: surf::StatusCode -> ApiErrorContext.status: http::StatusCode
• openrouter_rs::utils::{with_bearer_auth, with_request_metadata, with_client_request_headers, handle_error} -> caller-owned transport helpers or direct use of the canonical domain clients
• No API migration is required if you only use OpenRouterClient plus chat(), responses(), messages(), rerank(), audio(), images(), videos(), files(), models(), management(), and legacy()

Full migration guide: MIGRATION.md

• models().count() -> models().get_model_count()
• models().list_for_user() -> models().list_user_models()
• management().exchange_code_for_api_key(...) -> management().create_api_key_from_auth_code(...)
• management().list_guardrails(offset, limit) -> management().list_guardrails(Some(PaginationOptions::with_offset_and_limit(offset, limit)))
• client.list_api_keys(offset, include_disabled) -> management().list_api_keys(Some(PaginationOptions::with_offset(offset)), include_disabled)

0.6.0 removed the transitional aliases above; use the canonical method names shown here.

Prefer the just recipes so local work stays aligned with CI:

just quality
just quality-ci
just test-live-contract
OPENROUTER_MANAGEMENT_KEY=... just test-live-contract-management

Focused commands:

• just test-unit
• just test-lib
• just test-doc
• just test-integration-subsets
• just test-cli
• just check-migration-docs
• just test-migration-smoke
• just test-integration

Environment and model-pool details live in tests/integration/README.md. A starter env file lives at .env.example.

Start with docs/README.md for grouped navigation across root docs, docs/, specs/, and subsystem READMEs.

• MIGRATION.md for upgrade guidance across breaking SDK changes
• crates/openrouter-cli/README.md for CLI behavior, examples, and auth/config precedence
• CHANGELOG.md for release-by-release history

• CONTRIBUTING.md for contributor workflow and review expectations
• docs/policies/maintenance-policy.md for release, MSRV, and breaking-change policy
• docs/policies/compatibility-update-policy.md for upstream compatibility reporting cadence, templates, and update rules
• SECURITY.md for vulnerability reporting
• SUPPORT.md for support boundaries and issue-reporting guidance

• docs/design/generated-core-architecture.md for the generated-core plus idiomatic-wrapper design baseline
• docs/design/http-transport-migration.md for the historical design baseline behind the completed reqwest + rustls transport migration

• docs/operations/official-endpoint-test-matrix.md for endpoint-by-endpoint implementation and test status
• docs/operations/openapi-drift-reporting.md for weekly upstream-spec drift detection and baseline refresh workflow
• docs/operations/cli-automation-workflows.md for JSON-first shell and CI recipes built around openrouter-cli
• tests/integration/README.md for live test pools and env switches
• docs/community/awesome-openrouter/README.md for the Awesome OpenRouter submission kit and directory-safe assets

• Added Intern daemon signing with an OIDC session carrying vault:read, BYOK declared regions, key budgets/last-used timestamps, expired-key filters, workspace moves and video expiration.
• Added speech turn input/instructions, portable deferred-tool controls across Chat/Messages/Responses, chat function deferral and Messages tool-search result blocks.
• Breaking: SpeechRequest::input (including the TTS alias) now uses SpeechInput for text or turns. Existing text builder calls work unchanged; direct field access needs the 0.19 migration notes.
• Added explicit key-limit clearing and preserved existing PATCH clear operations through JSON round trips. Corrected the legacy reasoning test and accepted the October 13 OpenAPI snapshot (138 / 151 implemented; 13 deferred).

• Added prompt-cache usage details and assistant-message replay helpers that preserve modeled metadata, including reasoning summaries, signed/encrypted reasoning, and null content. Updated non-streaming and streaming tool-agent examples to retain context.
• Added end-user registration management and organization settings, plus Batch fallback, audio provider, and activity cache-token fields. Preserved generic server-tool request types.
• Accepted the October 6 OpenAPI review with 136 / 149 operations implemented and 13 explicitly deferred. Absent reasoning text/data fields now serialize as omitted rather than null.

• Added asynchronous Batch APIs, Intern invocation/daemon access, shared provider options, audio URL/image references, transcription metadata, and SCIM filters.
• Hardened credential response errors, forwarded Batch/Intern/SCIM attribution headers, and rejected empty audio URLs.
• Deprecated daemon-access and Coinbase charge aliases with documented replacements; retained compatibility entry points. Accepted the September 30 OpenAPI review with 129 / 142 operations implemented and 13 explicitly deferred.

• Added typed Intern lifecycle and streaming chat, workspace/intern vault secrets, and Decisions/System One domain clients, with runnable examples.
• Accepted the 2026-09-23 OpenAPI drift across all 122 / 122 operations, including current API-key, BYOK, audio, embedding, image, message, rerank, video, workspace, generation, and model-endpoint schemas.

• Added container files, workload OAuth token exchange/signing keys, SCIM sync jobs, regional management controls, and expanded message/model fields. Accepted the 2026-09-08 OpenAPI review with 105 / 105 tracked operations.

• Added session-cost datasets, single-interval workspace budgets, activity workspace filters, benchmark search filters, speech voice cloning, observability generation broadcast flags, and stored generation content errors.

• Breaking: ByokKey::workspace_id is now optional, and delete_workspace(...) takes an optional confirm_default_workspace_deletion argument.

• Accepted the 2026-08-17 OpenAPI drift review and restored tracked endpoint coverage to 97 / 97.

• Tool-aware chat streaming now preserves provider-supplied tool-call indices without inventing missing values, and FinishReason::Other keeps unknown provider finish reasons forward-compatible.
• Added SCIM group and group-role mapping management plus provider-aware Files API support.
• Accepted the 2026-08-03 OpenAPI drift review and restored tracked endpoint coverage to 95 / 95.

• Added explicit prompt-cache controls, static predicted output, image provider routing, conditional pricing overrides, cache-creation usage details, and guardrail flag actions.
• Added assistant-message model annotations, BYOK-aware guardrail/workspace budgets, workspace default guardrail IDs, transcription speaker labels, and Anthropic compaction/dynamic-tool blocks.
• Enabled image-only video requests and kept the accepted OpenAPI snapshot at 89 / 89 through the 2026-07-28 review.
• Breaking: workspace budget upserts now return UpsertWorkspaceBudgetResponse; read the budget from .data.
• Breaking: direct construction or matching of ContentPart::Text must account for prompt_cache_breakpoint; prefer the provided constructors or .. patterns.

• Added OpenRouter server-tool request helpers for chat completions, Responses API, Anthropic-compatible Messages, and preset creation request bodies.
• Added management-key SDK support for generation feedback and workspace member listing.
• Added model/rankings filters, analytics classifier controls, verbose transcription fields, XAI ZDR policy, routed service tiers, server-tool reasoning details, and image text chunks.
• Accepted OpenAPI drift through 2026-07-14 and restored tracked endpoint coverage to 89 / 89.

• Accepted OpenRouter's new max reasoning effort and preserved future provider-defined effort strings in model metadata, keeping /models deserialization and CLI model listing forward-compatible with upstream taxonomy additions.
• Hardened scheduled live Responses checks so transient runtime statuses stay service warnings while completed empty outputs, SDK deserialization failures, and non-retryable API errors remain hard failures.

• Added typed SDK coverage for image generation, files, analytics, app rankings, task classifications, unified benchmarks, singular model lookup, rankings-daily, preset listing/readback/versioning, workspace budgets, and expanded model filters.
• Added automatic prompt caching request support through top-level cache_control builders for chat completions and Responses API requests.
• Refreshed multimodal and metadata schemas, including rerank image-only document echoes, nullable model/generation metadata, Responses debug options, and Anthropic Messages system-role helpers.
• Accepted OpenAPI drift through the 2026-06-29 review and restored the tracked endpoint snapshot to 87 / 87.

• Marked high-churn public SDK request, response, metadata, usage, pricing, discovery, streaming, and upstream taxonomy types as #[non_exhaustive]; use builders, constructors, helpers, serde deserialization, or wildcard enum arms when migrating from 0.9.x.
• Added typed SDK coverage for audio transcriptions, BYOK provider credentials, observability destinations, multimodal embedding media parts, experimental response metadata, and model/generation metadata refreshes.
• Added OpenRouterClientBuilder::http_client(...) for injecting a custom reqwest::Client while preserving the default transport when omitted.
• Accepted OpenAPI drift through the 2026-05-19 review and restored the tracked endpoint snapshot to 62 / 62, while preserving OpenRouter metadata on normalized API errors and Anthropic Messages stream stop events.

• Added the canonical audio().speech() SDK surface for official /audio/speech, with deprecated tts() compatibility aliases.
• Expanded workspace, workspace-scoped keys/guardrails, workspace I/O logging, generation content/metadata, and video callback coverage while keeping the endpoint snapshot at 51 / 51.
• Marked high-churn public types as builder-first/future-proof and documented the 0.8.x -> 0.9.0 migration path.

• Added typed POST /tts support with the canonical tts() client surface and a runnable example.
• Added live smoke coverage for POST /rerank and GET /organization/members, and restored the repo snapshot to 43 / 43 accepted OpenAPI endpoints.
• Added openrouter-cli organization members list and aligned the CLI/docs surface with the latest management coverage.

• Completed the SDK transport migration to reqwest + rustls and removed the legacy surf / curl dependency chain.
• Made the public HTTP error surface backend-neutral and documented the 0.7.x -> 0.8.0 breaking changes.
• Expanded the repo snapshot with rerank, video, and organization-member coverage plus refreshed examples and CLI automation docs.

• Removed the SDK-level config surface and kept file/profile config out of the core crate.
• Standardized the canonical domain-oriented client docs around the 0.7.x API surface.
• Improved error normalization for HTTP 200 payloads that actually contain API error bodies.

See CONTRIBUTING.md for the full contributor workflow.

At a minimum, if you change public API surface, examples, or docs:

• update the relevant README/docs in the same change
• run just quality
• run just quality-ci if you touched migration docs, CLI behavior, or CI-aligned release/test flows

Related policies:

• docs/policies/maintenance-policy.md
• SECURITY.md
• SUPPORT.md

MIT. See LICENSE.