1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
//! # OpenRouter API Endpoints
//!
//! This module provides implementations for all OpenRouter API endpoints,
//! organized by functionality. Each submodule contains the request/response
//! types and methods for interacting with specific API endpoints.
//!
//! ## 📡 Available Endpoints
//!
//! ### Chat Completions ([`chat`])
//! Modern chat-based API for conversational AI interactions:
//! - Standard chat completions
//! - Streaming responses
//! - Reasoning tokens support
//! - System/user/assistant message handling
//!
//! ```rust
//! use openrouter_rs::api::chat::{ChatCompletionRequest, Message};
//! use openrouter_rs::types::Role;
//!
//! let request = ChatCompletionRequest::builder()
//! .model("anthropic/claude-sonnet-4")
//! .messages(vec![Message::new(Role::User, "Hello, world!")])
//! .build()?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ### Legacy Text Completions (`legacy-completions` feature)
//! Legacy prompt-based completions are isolated behind an explicit namespace:
//! - module path: `api::legacy::completion`
//! - client path: `client.legacy().completions().create(...)`
//! - intended only for migration/backward compatibility
//!
//! ### Model Information ([`models`])
//! Retrieve information about available models:
//! - List all available models
//! - Filter by category (programming, reasoning, etc.)
//! - Filter by supported parameters
//! - Get detailed model specifications
//!
//! ```rust
//! use openrouter_rs::types::ModelCategory;
//!
//! // Get all models in the programming category
//! let models = client.models().list_by_category(ModelCategory::Programming).await?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! ### API Key Management ([`api_keys`])
//! Manage and validate API keys:
//! - Get current API key information
//! - List all API keys for account
//! - Validate key permissions
//!
//! ### Credit Management ([`credits`])
//! Monitor usage and billing:
//! - Check current credit balance
//! - View usage statistics
//! - Track spending by model
//!
//! ### Generation Data ([`generation`])
//! Access detailed generation metadata:
//! - Token counts and pricing
//! - Model performance metrics
//! - Request/response timestamps
//!
//! ### Authentication ([`auth`])
//! Handle authentication and authorization:
//! - OAuth2 flows
//! - API key validation
//! - Permission management
//!
//! ### Error Handling ([`errors`])
//! Structured error responses from the API:
//! - Rate limiting errors
//! - Authentication failures
//! - Model availability issues
//!
//! ## 🚀 Quick Examples
//!
//! ### Basic Chat
//! ```rust
//! use openrouter_rs::{OpenRouterClient, api::chat::*};
//! use openrouter_rs::types::Role;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let client = OpenRouterClient::builder()
//! .api_key("your_key")
//! .build()?;
//!
//! let request = ChatCompletionRequest::builder()
//! .model("google/gemini-2.5-flash")
//! .messages(vec![Message::new(Role::User, "Hello!")])
//! .build()?;
//!
//! let response = client.chat().create(&request).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ### Model Discovery
//! ```rust
//! use openrouter_rs::OpenRouterClient;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let client = OpenRouterClient::builder()
//! .api_key("your_key")
//! .build()?;
//!
//! let models = client.models().list().await?;
//! println!("Found {} models", models.len());
//! # Ok(())
//! # }
//! ```
//!
//! ## ⚠️ Error Handling
//!
//! All API methods return `Result` types that should be handled appropriately:
//!
//! ```rust
//! use openrouter_rs::error::OpenRouterError;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! match client.chat().create(&request).await {
//! Ok(response) => println!("Success: {:?}", response),
//! Err(OpenRouterError::RateLimitExceeded) => {
//! println!("Rate limit hit, retrying later...");
//! }
//! Err(OpenRouterError::InvalidApiKey) => {
//! println!("Check your API key configuration");
//! }
//! Err(e) => println!("Other error: {}", e),
//! }
//! # Ok(())
//! # }
//! ```