api_openai/components/usage_shared.rs
1//! Structures related to API Usage and Costs endpoints.
2
3/// Define a private namespace for all its items.
4mod private
5{
6 // Serde imports
7 use serde::Deserialize;
8
9 /// Represents the monetary value and currency for a cost item.
10 ///
11 /// # Used By
12 /// - `CostsResult`
13 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
14 #[ non_exhaustive ]
15 pub struct CostsResultAmount
16 {
17 /// Lowercase ISO-4217 currency code (e.g., "usd").
18 pub currency : String,
19 /// The numeric value of the cost.
20 pub value : f64,
21 }
22
23 /// Represents the aggregated cost details for a specific time bucket and grouping.
24 ///
25 /// # Used By
26 /// - `UsageResult::Costs`
27 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
28 #[ non_exhaustive ]
29 pub struct CostsResult
30 {
31 /// The monetary value and currency.
32 pub amount : CostsResultAmount,
33 /// The invoice line item if grouped by `line_item`.
34 pub line_item : Option< String >,
35 /// Object type, always "organization.costs.result".
36 pub object : String,
37 /// The project ID if grouped by `project_id`.
38 pub project_id : Option< String >,
39 }
40
41 /// Represents aggregated usage details for the Audio Speeches API within a time bucket.
42 ///
43 /// # Used By
44 /// - `UsageResult::AudioSpeeches`
45 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
46 #[ non_exhaustive ]
47 pub struct UsageAudioSpeechesResult
48 {
49 /// The API key ID if grouped by `api_key_id`.
50 pub api_key_id : Option< String >,
51 /// The number of characters processed.
52 pub characters : i32,
53 /// The model name if grouped by `model`.
54 pub model : Option< String >,
55 /// The count of requests made to the model.
56 pub num_model_requests : i32,
57 /// Object type, always "`organization.usage.audio_speeches.result`".
58 pub object : String,
59 /// The project ID if grouped by `project_id`.
60 pub project_id : Option< String >,
61 /// The user ID if grouped by `user_id`.
62 pub user_id : Option< String >,
63 }
64
65 /// Represents aggregated usage details for the Audio Transcriptions API within a time bucket.
66 ///
67 /// # Used By
68 /// - `UsageResult::AudioTranscriptions`
69 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
70 #[ non_exhaustive ]
71 pub struct UsageAudioTranscriptionsResult
72 {
73 /// The API key ID if grouped by `api_key_id`.
74 pub api_key_id : Option< String >,
75 /// The model name if grouped by `model`.
76 pub model : Option< String >,
77 /// The count of requests made to the model.
78 pub num_model_requests : i32,
79 /// Object type, always "`organization.usage.audio_transcriptions.result`".
80 pub object : String,
81 /// The project ID if grouped by `project_id`.
82 pub project_id : Option< String >,
83 /// The number of seconds processed.
84 pub seconds : i32,
85 /// The user ID if grouped by `user_id`.
86 pub user_id : Option< String >,
87 }
88
89 /// Represents aggregated usage details for Code Interpreter sessions within a time bucket.
90 ///
91 /// # Used By
92 /// - `UsageResult::CodeInterpreter`
93 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
94 #[ non_exhaustive ]
95 pub struct UsageCodeInterpreterSessionsResult
96 {
97 /// The number of code interpreter sessions used.
98 pub num_sessions : i32, // Corrected field name from 'sessions' to 'num_sessions' based on example
99 /// Object type, always "`organization.usage.code_interpreter_sessions.result`".
100 pub object : String,
101 /// The project ID if grouped by `project_id`.
102 pub project_id : Option< String >,
103 }
104
105 /// Represents aggregated usage details for the Completions API within a time bucket.
106 ///
107 /// # Used By
108 /// - `UsageResult::Completions`
109 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
110 #[ non_exhaustive ]
111 pub struct UsageCompletionsResult
112 {
113 /// The API key ID if grouped by `api_key_id`.
114 pub api_key_id : Option< String >,
115 /// Whether the usage result is for batch jobs if grouped by `batch`.
116 pub batch : Option< bool >,
117 /// Aggregated number of audio input tokens used (including cached).
118 pub input_audio_tokens : Option< i32 >,
119 /// Aggregated number of text input tokens used (including cached).
120 pub input_tokens : i32,
121 /// The model name if grouped by `model`.
122 pub model : Option< String >,
123 /// The count of requests made to the model.
124 pub num_model_requests : i32,
125 /// Object type, always "organization.usage.completions.result".
126 pub object : String,
127 /// Aggregated number of audio output tokens used.
128 pub output_audio_tokens : Option< i32 >,
129 /// Aggregated number of text output tokens used.
130 pub output_tokens : i32,
131 /// The project ID if grouped by `project_id`.
132 pub project_id : Option< String >,
133 /// Aggregated number of cached text input tokens.
134 pub input_cached_tokens : Option< i32 >,
135 /// The user ID if grouped by `user_id`.
136 pub user_id : Option< String >,
137 }
138
139 /// Represents aggregated usage details for the Embeddings API within a time bucket.
140 ///
141 /// # Used By
142 /// - `UsageResult::Embeddings`
143 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
144 #[ non_exhaustive ]
145 pub struct UsageEmbeddingsResult
146 {
147 /// The API key ID if grouped by `api_key_id`.
148 pub api_key_id : Option< String >,
149 /// The aggregated number of input tokens used.
150 pub input_tokens : i32,
151 /// The model name if grouped by `model`.
152 pub model : Option< String >,
153 /// The count of requests made to the model.
154 pub num_model_requests : i32,
155 /// Object type, always "organization.usage.embeddings.result".
156 pub object : String,
157 /// The project ID if grouped by `project_id`.
158 pub project_id : Option< String >,
159 /// The user ID if grouped by `user_id`.
160 pub user_id : Option< String >,
161 }
162
163 /// Represents aggregated usage details for the Images API within a time bucket.
164 ///
165 /// # Used By
166 /// - `UsageResult::Images`
167 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
168 #[ non_exhaustive ]
169 pub struct UsageImagesResult
170 {
171 /// The API key ID if grouped by `api_key_id`.
172 pub api_key_id : Option< String >,
173 /// The number of images processed.
174 pub images : i32,
175 /// The model name if grouped by `model`.
176 pub model : Option< String >,
177 /// The count of requests made to the model.
178 pub num_model_requests : i32,
179 /// Object type, always "organization.usage.images.result".
180 pub object : String,
181 /// The project ID if grouped by `project_id`.
182 pub project_id : Option< String >,
183 /// The image size if grouped by `size` (e.g., "1024x1024").
184 pub size : Option< String >,
185 /// The source of the usage if grouped by `source` (e.g., "image.generation").
186 pub source : Option< String >,
187 /// The user ID if grouped by `user_id`.
188 pub user_id : Option< String >,
189 }
190
191 /// Represents aggregated usage details for the Moderations API within a time bucket.
192 ///
193 /// # Used By
194 /// - `UsageResult::Moderations`
195 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
196 #[ non_exhaustive ]
197 pub struct UsageModerationsResult
198 {
199 /// The API key ID if grouped by `api_key_id`.
200 pub api_key_id : Option< String >,
201 /// The aggregated number of input tokens used.
202 pub input_tokens : i32,
203 /// The model name if grouped by `model`.
204 pub model : Option< String >,
205 /// The count of requests made to the model.
206 pub num_model_requests : i32,
207 /// Object type, always "organization.usage.moderations.result".
208 pub object : String,
209 /// The project ID if grouped by `project_id`.
210 pub project_id : Option< String >,
211 /// The user ID if grouped by `user_id`.
212 pub user_id : Option< String >,
213 }
214
215 /// Represents aggregated usage details for Vector Stores within a time bucket.
216 ///
217 /// # Used By
218 /// - `UsageResult::VectorStores`
219 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
220 #[ non_exhaustive ]
221 pub struct UsageVectorStoresResult
222 {
223 /// Object type, always "`organization.usage.vector_stores.result`".
224 pub object : String,
225 /// The project ID if grouped by `project_id`.
226 pub project_id : Option< String >,
227 /// The vector stores usage in bytes.
228 pub usage_bytes : i64,
229 }
230
231 /// Represents the aggregated usage or cost result within a time bucket, varying by endpoint.
232 ///
233 /// # Used By
234 /// - `UsageTimeBucket`
235 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
236 #[ serde( untagged ) ]
237 #[ non_exhaustive ]
238 pub enum UsageResult
239 {
240 /// Audio Speeches API usage details.
241 AudioSpeeches( UsageAudioSpeechesResult ),
242 /// Audio Transcriptions API usage details.
243 AudioTranscriptions( UsageAudioTranscriptionsResult ),
244 /// Code Interpreter sessions usage details.
245 CodeInterpreter( UsageCodeInterpreterSessionsResult ),
246 /// Completions API usage details.
247 Completions( UsageCompletionsResult ),
248 /// Costs details.
249 Costs( CostsResult ),
250 /// Embeddings API usage details.
251 Embeddings( UsageEmbeddingsResult ),
252 /// Images API usage details.
253 Images( UsageImagesResult ),
254 /// Moderations API usage details.
255 Moderations( UsageModerationsResult ),
256 /// Vector Stores usage details.
257 VectorStores( UsageVectorStoresResult ),
258 }
259
260 /// Represents a time bucket containing aggregated usage or cost results.
261 ///
262 /// # Used By
263 /// - `UsageResponse`
264 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
265 #[ non_exhaustive ]
266 pub struct UsageTimeBucket
267 {
268 /// List of time buckets containing usage/cost data.
269 pub data : Vec< UsageResult >,
270 /// End timestamp of the bucket (Unix seconds).
271 pub end_time : i64,
272 /// Indicates if more data is available for pagination.
273 pub has_more : bool,
274 /// Pagination cursor for the next page.
275 pub next_page : Option< String >,
276 /// Object type, always "bucket".
277 pub object : String,
278 /// Start timestamp of the bucket (Unix seconds).
279 pub start_time : i64,
280 }
281
282 /// Represents the paginated response from a Usage or Costs API endpoint.
283 ///
284 /// # Used By
285 /// - `/organization/costs` (GET)
286 /// - `/organization/usage/*` (GET endpoints)
287 #[ derive( Debug, Deserialize, Clone, PartialEq ) ]
288 #[ non_exhaustive ]
289 pub struct UsageResponse
290 {
291 /// List of time buckets containing usage/cost data.
292 pub data : Vec< UsageTimeBucket >,
293 /// Indicates if more data is available for pagination.
294 pub has_more : bool,
295 /// Pagination cursor for the next page.
296 pub next_page : Option< String >,
297 /// Object type, always "page".
298 pub object : String,
299 }
300} // end mod private
301
302crate ::mod_interface!
303{
304 exposed use
305 {
306 CostsResultAmount,
307 CostsResult,
308 UsageAudioSpeechesResult,
309 UsageAudioTranscriptionsResult,
310 UsageCodeInterpreterSessionsResult,
311 UsageCompletionsResult,
312 UsageEmbeddingsResult,
313 UsageImagesResult,
314 UsageModerationsResult,
315 UsageVectorStoresResult,
316 UsageResult,
317 UsageTimeBucket,
318 UsageResponse
319 };
320}