openrouter/types/
discovery.rs

1//! Response types for the discovery endpoints (`/models`, `/models/{author}/{slug}/endpoints`,
2//! `/providers`).
3//!
4//! Shapes mirror the Go SDK (`metadata_models.go`) one-for-one so behavior stays
5//! aligned across the two ports.
6
7use serde::{Deserialize, Serialize};
8
9/// Optional query parameters for [`crate::Client::list_models`].
10#[derive(Clone, Debug, Default, PartialEq, Eq)]
11pub struct ListModelsOptions {
12    /// Filters models by category (e.g. `"programming"`). Results are sorted
13    /// from most to least used.
14    pub category: Option<String>,
15    /// Filters models by supported parameter (e.g. `"tools"`, `"temperature"`).
16    pub supported_parameters: Option<String>,
17}
18
19impl ListModelsOptions {
20    /// Start a new, empty options builder.
21    pub fn new() -> Self {
22        Self::default()
23    }
24
25    /// Set the `category` filter.
26    pub fn category(mut self, category: impl Into<String>) -> Self {
27        self.category = Some(category.into());
28        self
29    }
30
31    /// Set the `supported_parameters` filter.
32    pub fn supported_parameters(mut self, value: impl Into<String>) -> Self {
33        self.supported_parameters = Some(value.into());
34        self
35    }
36
37    pub(crate) fn to_query(&self) -> Vec<(&'static str, String)> {
38        let mut q = Vec::new();
39        if let Some(c) = &self.category {
40            q.push(("category", c.clone()));
41        }
42        if let Some(s) = &self.supported_parameters {
43            q.push(("supported_parameters", s.clone()));
44        }
45        q
46    }
47}
48
49/// Response from `GET /models`.
50#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
51pub struct ModelsResponse {
52    /// Model rows.
53    #[serde(default)]
54    pub data: Vec<Model>,
55}
56
57/// A single model available on OpenRouter.
58#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
59pub struct Model {
60    /// Model id (e.g. `google/gemini-3.1-flash-lite`).
61    pub id: String,
62    /// Display name.
63    #[serde(default)]
64    pub name: String,
65    /// Stable canonical slug (immutable across renames).
66    #[serde(default)]
67    pub canonical_slug: Option<String>,
68    /// Unix-seconds creation timestamp.
69    #[serde(default)]
70    pub created: Option<f64>,
71    /// Long description.
72    #[serde(default)]
73    pub description: String,
74    /// Maximum context window in tokens.
75    #[serde(default)]
76    pub context_length: Option<f64>,
77    /// Hugging Face model id, when published.
78    #[serde(default)]
79    pub hugging_face_id: Option<String>,
80    /// Model architecture summary.
81    #[serde(default)]
82    pub architecture: ModelArchitecture,
83    /// Description of the top provider serving this model.
84    #[serde(default)]
85    pub top_provider: ModelTopProvider,
86    /// Per-request token limits, when published.
87    #[serde(default)]
88    pub per_request_limits: Option<ModelPerRequestLimits>,
89    /// Supported parameter names.
90    #[serde(default)]
91    pub supported_parameters: Vec<String>,
92    /// Default sampling parameters published by the provider.
93    #[serde(default)]
94    pub default_parameters: Option<ModelDefaultParameters>,
95    /// Pricing breakdown.
96    #[serde(default)]
97    pub pricing: ModelPricing,
98    /// Model retirement date, when scheduled.
99    #[serde(default)]
100    pub expiration_date: Option<String>,
101}
102
103/// Architecture summary for a model.
104#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
105pub struct ModelArchitecture {
106    /// Input modalities (`text`, `image`, ...).
107    #[serde(default)]
108    pub input_modalities: Vec<String>,
109    /// Output modalities.
110    #[serde(default)]
111    pub output_modalities: Vec<String>,
112    /// Tokenizer name.
113    #[serde(default)]
114    pub tokenizer: String,
115    /// Instruction-tuning family.
116    #[serde(default)]
117    pub instruct_type: Option<String>,
118    /// Combined modality string for legacy clients.
119    #[serde(default)]
120    pub modality: Option<String>,
121}
122
123/// Top-provider summary for a model.
124#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
125pub struct ModelTopProvider {
126    /// Context length advertised by the top provider.
127    #[serde(default)]
128    pub context_length: Option<f64>,
129    /// Max completion tokens.
130    #[serde(default)]
131    pub max_completion_tokens: Option<f64>,
132    /// True if the top provider applies content moderation.
133    #[serde(default)]
134    pub is_moderated: bool,
135}
136
137/// Per-request token limits.
138#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
139pub struct ModelPerRequestLimits {
140    /// Max prompt tokens per request.
141    #[serde(default)]
142    pub prompt_tokens: Option<f64>,
143    /// Max completion tokens per request.
144    #[serde(default)]
145    pub completion_tokens: Option<f64>,
146}
147
148/// Default sampling parameters published by the provider.
149#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
150pub struct ModelDefaultParameters {
151    /// Default temperature.
152    #[serde(default)]
153    pub temperature: Option<f64>,
154    /// Default top-p.
155    #[serde(default)]
156    pub top_p: Option<f64>,
157    /// Default frequency penalty.
158    #[serde(default)]
159    pub frequency_penalty: Option<f64>,
160}
161
162/// Pricing expressed as decimal strings (USD per token / per request / per image).
163#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
164pub struct ModelPricing {
165    /// Per-prompt-token cost.
166    #[serde(default)]
167    pub prompt: String,
168    /// Per-completion-token cost.
169    #[serde(default)]
170    pub completion: String,
171    /// Per-image cost.
172    #[serde(default)]
173    pub image: String,
174    /// Per-request flat fee.
175    #[serde(default)]
176    pub request: String,
177    /// Cached-input read cost.
178    #[serde(default)]
179    pub input_cache_read: Option<String>,
180    /// Cached-input write cost.
181    #[serde(default)]
182    pub input_cache_write: Option<String>,
183    /// Web-search invocation cost.
184    #[serde(default)]
185    pub web_search: String,
186    /// Internal reasoning token cost.
187    #[serde(default)]
188    pub internal_reasoning: String,
189}
190
191/// Response from `GET /models/{author}/{slug}/endpoints`.
192#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
193pub struct ModelEndpointsResponse {
194    /// Model + endpoint payload.
195    #[serde(default)]
196    pub data: ModelEndpointsData,
197}
198
199/// Body of [`ModelEndpointsResponse`].
200#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
201pub struct ModelEndpointsData {
202    /// Model id.
203    #[serde(default)]
204    pub id: String,
205    /// Display name.
206    #[serde(default)]
207    pub name: String,
208    /// Unix-seconds creation timestamp.
209    #[serde(default)]
210    pub created: Option<f64>,
211    /// Long description.
212    #[serde(default)]
213    pub description: String,
214    /// Architecture summary.
215    #[serde(default)]
216    pub architecture: ModelEndpointsArchitecture,
217    /// Endpoint rows.
218    #[serde(default)]
219    pub endpoints: Vec<ModelEndpoint>,
220}
221
222/// Architecture summary specific to the endpoints listing.
223#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
224pub struct ModelEndpointsArchitecture {
225    /// Tokenizer name.
226    #[serde(default)]
227    pub tokenizer: Option<String>,
228    /// Instruction-tuning family.
229    #[serde(default)]
230    pub instruct_type: Option<String>,
231    /// Input modalities.
232    #[serde(default)]
233    pub input_modalities: Vec<String>,
234    /// Output modalities.
235    #[serde(default)]
236    pub output_modalities: Vec<String>,
237}
238
239/// A single provider endpoint for a model.
240#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
241pub struct ModelEndpoint {
242    /// Endpoint display name.
243    #[serde(default)]
244    pub name: String,
245    /// Context window in tokens.
246    #[serde(default)]
247    pub context_length: f64,
248    /// Pricing information.
249    #[serde(default)]
250    pub pricing: ModelEndpointPricing,
251    /// Provider serving this endpoint.
252    #[serde(default)]
253    pub provider_name: String,
254    /// Weight quantization label.
255    #[serde(default)]
256    pub quantization: Option<String>,
257    /// Maximum completion tokens supported.
258    #[serde(default)]
259    pub max_completion_tokens: Option<f64>,
260    /// Maximum prompt tokens supported.
261    #[serde(default)]
262    pub max_prompt_tokens: Option<f64>,
263    /// Provider-advertised supported parameter names.
264    #[serde(default)]
265    pub supported_parameters: Vec<String>,
266    /// Operational status (0 = healthy).
267    #[serde(default)]
268    pub status: f64,
269    /// Rolling 30-minute uptime ratio.
270    #[serde(default)]
271    pub uptime_last_30m: Option<f64>,
272}
273
274/// Endpoint-specific pricing.
275#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
276pub struct ModelEndpointPricing {
277    /// Per-request flat fee.
278    #[serde(default)]
279    pub request: String,
280    /// Per-image cost.
281    #[serde(default)]
282    pub image: String,
283    /// Per-prompt-token cost.
284    #[serde(default)]
285    pub prompt: String,
286    /// Per-completion-token cost.
287    #[serde(default)]
288    pub completion: String,
289}
290
291/// Response from `GET /providers`.
292#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
293pub struct ProvidersResponse {
294    /// Provider rows.
295    #[serde(default)]
296    pub data: Vec<ProviderInfo>,
297}
298
299/// Information about a provider available on OpenRouter.
300#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
301pub struct ProviderInfo {
302    /// Provider name.
303    #[serde(default)]
304    pub name: String,
305    /// Provider slug used in routing parameters.
306    #[serde(default)]
307    pub slug: String,
308    /// Privacy-policy URL.
309    #[serde(default)]
310    pub privacy_policy_url: Option<String>,
311    /// Terms-of-service URL.
312    #[serde(default)]
313    pub terms_of_service_url: Option<String>,
314    /// Public status-page URL.
315    #[serde(default)]
316    pub status_page_url: Option<String>,
317}
openrouter/types/discovery.rs

openrouter/types/
discovery.rs
