OpenRouter Rust

A comprehensive, type-safe Rust client library for the OpenRouter API.

Features

🤖 Chat Completions API: Full support for /v1/chat/completions endpoint
🆕 Responses API (Beta): Support for the new /v1/responses endpoint with reasoning capabilities
🎭 Anthropic Messages API: Native support for Anthropic's Messages API format
🔢 Embeddings API: Text and multimodal embeddings support
📊 Models API: List, filter, and query available models
🏢 Providers API: List available model providers
📈 Generation API: Retrieve detailed generation metadata
🌊 Streaming: Real-time streaming responses using Server-Sent Events (SSE)
🔒 Type-Safe: Comprehensive types for all API requests and responses
🏗️ Builder Pattern: Ergonomic builder APIs for constructing requests
⚡ Async/Await: Fully async with tokio runtime
📦 Modular: Use only the features you need
🛠️ Error Handling: Detailed error types for different failure scenarios

Installation

Add this to your Cargo.toml:

[dependencies]
openrouter-rust = "0.1.0"

Or with specific features:

[dependencies]
openrouter-rust = { version = "0.1.0", features = ["chat", "streaming", "embeddings", "anthropic"] }

Feature Flags

chat (default): Enable chat completions API (/v1/chat/completions)
responses: Enable Responses API (/v1/responses)
streaming (default): Enable streaming support
embeddings: Enable embeddings API (/v1/embeddings)
anthropic: Enable Anthropic Messages API (/v1/messages)
providers (default): Enable providers API (/v1/providers)
models (default): Enable models API (/v1/models, /v1/models/count, /v1/models/user)
generations (default): Enable generation metadata API (/v1/generation)

Quick Start

use openrouter_rust::{OpenRouterClient, ChatCompletionBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a client
    let client = OpenRouterClient::builder()
        .api_key("your-openrouter-api-key")
        .build()?;

    // Build and send a request
    let request = ChatCompletionBuilder::new("openai/gpt-3.5-turbo")
        .system_message("You are a helpful assistant.")
        .user_message("What is the meaning of life?")
        .temperature(0.7)
        .build();

    let response = client.chat_completion(request).await?;
    
    if let Some(ref content) = response.choices[0].message.content {
        println!("Response: {}", content);
    }
    
    Ok(())
}

Usage Examples

Basic Chat Completion

use openrouter_rust::{OpenRouterClient, ChatCompletionBuilder};

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .http_referer("https://your-site.com")
    .x_title("My App")
    .build()?;

let request = ChatCompletionBuilder::new("openai/gpt-3.5-turbo")
    .system_message("You are a helpful coding assistant.")
    .user_message("Write a function to reverse a string in Rust.")
    .temperature(0.7)
    .max_tokens(500)
    .build();

let response = client.chat_completion(request).await?;
if let Some(ref content) = response.choices[0].message.content {
    println!("{}", content);
}

Streaming Responses

use openrouter_rust::{OpenRouterClient, ChatCompletionBuilder};
use futures::StreamExt;

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .build()?;

let request = ChatCompletionBuilder::new("openai/gpt-3.5-turbo")
    .user_message("Write a story about a robot learning to paint.")
    .stream(true)
    .build();

let stream = client.chat_completion_stream(request).await?;
let mut stream = stream;

while let Some(result) = stream.next().await {
    match result {
        Ok(chunk) => {
            for choice in &chunk.choices {
                if let Some(ref content) = choice.delta.content {
                    print!("{}", content);
                }
            }
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

Anthropic Messages API

use openrouter_rust::{OpenRouterClient, anthropic::AnthropicMessageBuilder};

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .build()?;

let request = AnthropicMessageBuilder::new("anthropic/claude-3.5-sonnet", 1024)
    .user_message("Explain how neural networks work.")
    .thinking(2000)
    .temperature(0.7)
    .build();

let response = client.create_anthropic_message(request).await?;

for content in &response.content {
    match content {
        openrouter_rust::anthropic::AnthropicResponseContent::Text { text } => {
            println!("{}", text);
        }
        openrouter_rust::anthropic::AnthropicResponseContent::Thinking { thinking, .. } => {
            println!("Thinking: {}", thinking);
        }
        _ => {}
    }
}

println!("Tokens used: {}", response.usage.input_tokens + response.usage.output_tokens);

Embeddings API

use openrouter_rust::{OpenRouterClient, embeddings::EmbeddingBuilder};

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .build()?;

// Single text embedding
let request = EmbeddingBuilder::new("text-embedding-ada-002", "The quick brown fox")
    .build();

let response = client.create_embedding(request).await?;

for item in &response.data {
    match &item.embedding {
        openrouter_rust::embeddings::EmbeddingData::FloatArray(vec) => {
            println!("Embedding dimensions: {}", vec.len());
        }
        _ => {}
    }
}

// Batch embeddings
let batch_request = EmbeddingBuilder::new_with_array(
    "text-embedding-ada-002",
    vec!["First text".to_string(), "Second text".to_string()]
).build();

let batch_response = client.create_embedding(batch_request).await?;
println!("Generated {} embeddings", batch_response.data.len());

// List available embedding models
let models = client.list_embedding_models().await?;
for model in &models.data {
    println!("Model: {} - {}", model.id, model.description);
}

Responses API (Beta)

use openrouter_rust::{OpenRouterClient, responses::ResponsesRequestBuilder};

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .build()?;

let request = ResponsesRequestBuilder::new("anthropic/claude-3.5-sonnet")
    .user_message("Explain quantum computing in simple terms.")
    .reasoning("medium")
    .temperature(0.8)
    .build();

let response = client.create_response(request).await?;

for item in &response.output {
    match item {
        openrouter_rust::responses::OutputItem::Message { content, .. } => {
            for c in content {
                if let openrouter_rust::responses::OutputContent::Text { text, .. } = c {
                    println!("{}", text);
                }
            }
        }
        openrouter_rust::responses::OutputItem::Reasoning { summary, .. } => {
            println!("Reasoning summary available");
        }
        _ => {}
    }
}

Models API

use openrouter_rust::{OpenRouterClient, models::ListModelsParams};

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .build()?;

// List all models
let models = client.list_models(None).await?;
for model in &models.data {
    println!("{} - {}", model.id, model.name);
    println!("  Context length: {:?}", model.context_length);
    println!("  Supports: {:?}", model.supported_parameters);
}

// Get model count
let count = client.get_models_count().await?;
println!("Total models available: {}", count.data.count);

// List models filtered by user preferences
let user_models = client.list_models_user().await?;

// Filter models by category
let params = ListModelsParams {
    category: Some("programming".to_string()),
    ..Default::default()
};
let programming_models = client.list_models(Some(params)).await?;

Providers API

use openrouter_rust::OpenRouterClient;

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .build()?;

let providers = client.list_providers().await?;
for provider in &providers.data {
    println!("Provider: {}", provider.name);
    println!("  Slug: {}", provider.slug);
    if let Some(ref privacy) = provider.privacy_policy_url {
        println!("  Privacy Policy: {}", privacy);
    }
}

Generation Metadata API

use openrouter_rust::OpenRouterClient;

let client = OpenRouterClient::builder()
    .api_key(std::env::var("OPENROUTER_API_KEY")?)
    .build()?;

// After making a chat completion, get the generation ID from the response
let generation_id = "gen-1234567890abcdef";

let generation = client.get_generation(generation_id).await?;
let data = &generation.data;

println!("Generation ID: {}", data.id);
println!("Model: {}", data.model);
println!("Total cost: ${:.6}", data.total_cost);
println!("Tokens: {} prompt, {} completion", 
    data.tokens_prompt.unwrap_or(0.0), 
    data.tokens_completion.unwrap_or(0.0)
);
println!("Latency: {}ms", data.latency.unwrap_or(0.0));
println!("Provider: {:?}", data.provider_name);

JSON Mode

use openrouter_rust::{OpenRouterClient, ChatCompletionBuilder};

let request = ChatCompletionBuilder::new("openai/gpt-3.5-turbo")
    .system_message("You are a helpful assistant that only responds in JSON.")
    .user_message("List 3 programming languages and their paradigms.")
    .response_format_json()
    .build();

let response = client.chat_completion(request).await?;
// Response will be valid JSON

Tool Calling

use openrouter_rust::{
    OpenRouterClient,
    ChatCompletionBuilder,
    types::{Tool, Function},
};
use serde_json::json;

let weather_tool = Tool {
    tool_type: "function".to_string(),
    function: Function {
        name: "get_weather".to_string(),
        description: Some("Get the current weather in a location".to_string()),
        parameters: json!({
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state"
                }
            },
            "required": ["location"]
        }),
    },
};

let request = ChatCompletionBuilder::new("openai/gpt-3.5-turbo")
    .user_message("What's the weather in Paris?")
    .tools(vec![weather_tool])
    .build();

Configuration

Client Builder Options

let client = OpenRouterClient::builder()
    .api_key("your-api-key")                    // Required
    .base_url("https://openrouter.ai/api/v1")   // Optional, defaults to official API
    .http_referer("https://your-site.com")      // Optional, for OpenRouter rankings
    .x_title("Your App Name")                   // Optional, for OpenRouter rankings
    .timeout(std::time::Duration::from_secs(60)) // Optional, default 60s
    .build()?;

Error Handling

The library provides detailed error types:

use openrouter_rust::OpenRouterError;

match result {
    Err(OpenRouterError::ApiError { code, message }) => {
        println!("API error {}: {}", code, message);
    }
    Err(OpenRouterError::AuthenticationError(msg)) => {
        println!("Auth error: {}", msg);
    }
    Err(OpenRouterError::RateLimitError) => {
        println!("Rate limit exceeded, retry later");
    }
    Err(OpenRouterError::HttpError(e)) => {
        println!("HTTP error: {}", e);
    }
    Err(OpenRouterError::JsonError(e)) => {
        println!("JSON error: {}", e);
    }
    _ => {}
}

Examples

See the examples/ directory for complete working examples:

basic_chat.rs - Simple chat completion
streaming.rs - Real-time streaming
responses_api.rs - Using the new Responses API
anthropic_messages.rs - Anthropic Messages API usage
embeddings.rs - Text and image embeddings
models_api.rs - Listing and filtering models
providers.rs - Listing providers
generation_metadata.rs - Retrieving generation info

Run examples:

export OPENROUTER_API_KEY="your-api-key"

# Basic examples (chat features)
cargo run --example basic_chat
cargo run --example streaming --features streaming
cargo run --example anthropic_messages --features anthropic

# Advanced features
cargo run --example responses_api --features responses
cargo run --example embeddings --features embeddings
cargo run --example models_api --features models
cargo run --example providers --features providers
cargo run --example generation_metadata --features generations

API Coverage

Implemented ✅

✅ Chat Completions (/v1/chat/completions)
✅ Responses API (/v1/responses)
✅ Anthropic Messages (/v1/messages)
✅ Embeddings (/v1/embeddings, /v1/embeddings/models)
✅ Models (/v1/models, /v1/models/count, /v1/models/user)
✅ Providers (/v1/providers)
✅ Generation Metadata (/v1/generation)
✅ Streaming (SSE)
✅ All standard parameters (temperature, top_p, max_tokens, etc.)
✅ Tools/Function calling
✅ JSON mode
✅ Provider preferences
✅ Plugins (web search, auto-router, etc.)

Coming Soon 🔄

🔄 Image generation
🔄 Audio APIs (TTS, STT)
🔄 Batch processing
🔄 Fine-tuning

License

This project is licensed under the MIT OR Apache-2.0 license.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

Made with ❤️ for the Rust community

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenRouter Rust

Features

Installation

Feature Flags

Quick Start

Usage Examples

Basic Chat Completion

Streaming Responses

Anthropic Messages API

Embeddings API

Responses API (Beta)

Models API

Providers API

Generation Metadata API

JSON Mode

Tool Calling

Configuration

Client Builder Options

Error Handling

Examples

API Coverage

Implemented ✅

Coming Soon 🔄

License

Contributing

Support

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

OpenRouter Rust

Features

Installation

Feature Flags

Quick Start

Usage Examples

Basic Chat Completion

Streaming Responses

Anthropic Messages API

Embeddings API

Responses API (Beta)

Models API

Providers API

Generation Metadata API

JSON Mode

Tool Calling

Configuration

Client Builder Options

Error Handling

Examples

API Coverage

Implemented ✅

Coming Soon 🔄

License

Contributing

Support