async_openai/types/batches/batch.rs
1use std::collections::HashMap;
2
3use derive_builder::Builder;
4use serde::{Deserialize, Serialize};
5
6use crate::error::OpenAIError;
7use crate::types::batches::ResponseUsage;
8use crate::types::Metadata;
9
10#[derive(Debug, Serialize, Default, Clone, Builder, PartialEq, Deserialize)]
11#[builder(name = "BatchRequestArgs")]
12#[builder(pattern = "mutable")]
13#[builder(setter(into, strip_option), default)]
14#[builder(derive(Debug))]
15#[builder(build_fn(error = "OpenAIError"))]
16pub struct BatchRequest {
17 /// The ID of an uploaded file that contains requests for the new batch.
18 ///
19 /// See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.
20 ///
21 /// Your input file must be formatted as a [JSONL file](https://platform.openai.com/docs/api-reference/batch/request-input), and must be uploaded with the purpose `batch`. The file can contain up to 50,000 requests, and can be up to 200 MB in size.
22 pub input_file_id: String,
23
24 /// The endpoint to be used for all requests in the batch. Currently `/v1/responses`,
25 /// `/v1/chat/completions`, `/v1/embeddings`, `/v1/completions`, and `/v1/moderations` are
26 /// supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000
27 /// embedding inputs across all requests in the batch.
28 pub endpoint: BatchEndpoint,
29
30 /// The time frame within which the batch should be processed. Currently only `24h` is supported.
31 pub completion_window: BatchCompletionWindow,
32
33 /// Optional custom metadata for the batch.
34 pub metadata: Option<HashMap<String, serde_json::Value>>,
35
36 /// The expiration policy for the output and/or error file that are generated for a batch.
37 pub output_expires_after: Option<BatchFileExpirationAfter>,
38}
39
40#[derive(Debug, Clone, PartialEq, Deserialize, Serialize, Default)]
41pub enum BatchEndpoint {
42 #[default]
43 #[serde(rename = "/v1/responses")]
44 V1Responses,
45 #[serde(rename = "/v1/chat/completions")]
46 V1ChatCompletions,
47 #[serde(rename = "/v1/embeddings")]
48 V1Embeddings,
49 #[serde(rename = "/v1/completions")]
50 V1Completions,
51 #[serde(rename = "/v1/moderations")]
52 V1Moderations,
53}
54
55#[derive(Debug, Clone, PartialEq, Serialize, Default, Deserialize)]
56pub enum BatchCompletionWindow {
57 #[default]
58 #[serde(rename = "24h")]
59 W24H,
60}
61
62/// File expiration policy
63///
64/// The expiration policy for the output and/or error file that are generated for a batch.
65#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
66pub struct BatchFileExpirationAfter {
67 /// Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`. Note that the anchor is the file creation time, not the time the batch is created.
68 pub anchor: BatchFileExpirationAnchor,
69 /// The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
70 pub seconds: u32,
71}
72
73#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
74#[serde(rename_all = "snake_case")]
75pub enum BatchFileExpirationAnchor {
76 CreatedAt,
77}
78
79#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
80pub struct Batch {
81 pub id: String,
82 /// The object type, which is always `batch`.
83 pub object: String,
84 /// The OpenAI API endpoint used by the batch.
85 pub endpoint: String,
86 /// Model ID used to process the batch, like `gpt-6-astra`. OpenAI
87 /// offers a wide range of models with different capabilities, performance
88 /// characteristics, and price points. Refer to the [model
89 /// guide](https://platform.openai.com/docs/models) to browse and compare available models.
90 pub model: Option<String>,
91 pub errors: Option<BatchErrors>,
92 /// The ID of the input file for the batch.
93 pub input_file_id: String,
94 /// The time frame within which the batch should be processed.
95 pub completion_window: String,
96 /// The current status of the batch.
97 pub status: BatchStatus,
98 /// The ID of the file containing the outputs of successfully executed requests.
99 pub output_file_id: Option<String>,
100 /// The ID of the file containing the outputs of requests with errors.
101 pub error_file_id: Option<String>,
102 /// The Unix timestamp (in seconds) for when the batch was created.
103 pub created_at: u64,
104 /// The Unix timestamp (in seconds) for when the batch started processing.
105 pub in_progress_at: Option<u64>,
106 /// The Unix timestamp (in seconds) for when the batch will expire.
107 pub expires_at: Option<u64>,
108 /// The Unix timestamp (in seconds) for when the batch started finalizing.
109 pub finalizing_at: Option<u64>,
110 /// The Unix timestamp (in seconds) for when the batch was completed.
111 pub completed_at: Option<u64>,
112 /// The Unix timestamp (in seconds) for when the batch failed.
113 pub failed_at: Option<u64>,
114 /// The Unix timestamp (in seconds) for when the batch expired.
115 pub expired_at: Option<u64>,
116 /// The Unix timestamp (in seconds) for when the batch started cancelling.
117 pub cancelling_at: Option<u64>,
118 /// The Unix timestamp (in seconds) for when the batch was cancelled.
119 pub cancelled_at: Option<u64>,
120 /// The request counts for different statuses within the batch.
121 pub request_counts: Option<BatchRequestCounts>,
122 /// Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used. Only populated on batches created after September 7, 2025.
123 pub usage: Option<ResponseUsage>,
124 /// Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.
125 pub metadata: Option<Metadata>,
126}
127
128#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
129pub struct BatchErrors {
130 /// The object type, which is always `list`.
131 pub object: String,
132 pub data: Vec<BatchError>,
133}
134
135#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
136pub struct BatchError {
137 /// An error code identifying the error type.
138 pub code: String,
139 /// A human-readable message providing more details about the error.
140 pub message: String,
141 /// The name of the parameter that caused the error, if applicable.
142 pub param: Option<String>,
143 /// The line number of the input file where the error occurred, if applicable.
144 pub line: Option<u32>,
145}
146
147#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
148#[serde(rename_all = "snake_case")]
149pub enum BatchStatus {
150 Validating,
151 Failed,
152 InProgress,
153 Finalizing,
154 Completed,
155 Expired,
156 Cancelling,
157 Cancelled,
158}
159
160#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
161pub struct BatchRequestCounts {
162 /// Total number of requests in the batch.
163 pub total: u32,
164 /// Number of requests that have been completed successfully.
165 pub completed: u32,
166 /// Number of requests that have failed.
167 pub failed: u32,
168}
169
170#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
171pub struct ListBatchesResponse {
172 pub data: Vec<Batch>,
173 pub first_id: Option<String>,
174 pub last_id: Option<String>,
175 pub has_more: bool,
176 pub object: String,
177}
178
179#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
180#[serde(rename_all = "UPPERCASE")]
181pub enum BatchRequestInputMethod {
182 POST,
183}
184
185/// The per-line object of the batch input file
186#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
187pub struct BatchRequestInput {
188 /// A developer-provided per-request id that will be used to match outputs to inputs. Must be unique for each request in a batch.
189 pub custom_id: String,
190 /// The HTTP method to be used for the request. Currently only `POST` is supported.
191 pub method: BatchRequestInputMethod,
192 /// The OpenAI API relative URL to be used for the request. Currently `/v1/responses`,
193 /// `/v1/chat/completions`, `/v1/embeddings`, `/v1/completions`, and `/v1/moderations` are supported.
194 pub url: BatchEndpoint,
195 pub body: Option<serde_json::Value>,
196}
197
198#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
199pub struct BatchRequestOutputResponse {
200 /// The HTTP status code of the response
201 pub status_code: u16,
202 /// An unique identifier for the OpenAI API request. Please include this request ID when contacting support.
203 pub request_id: String,
204 /// The JSON body of the response
205 pub body: serde_json::Value,
206}
207
208#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
209pub struct BatchRequestOutputError {
210 /// A machine-readable error code.
211 pub code: String,
212 /// A human-readable error message.
213 pub message: String,
214}
215
216/// The per-line object of the batch output and error files
217#[derive(Debug, Deserialize, Clone, PartialEq, Serialize)]
218pub struct BatchRequestOutput {
219 pub id: String,
220 /// A developer-provided per-request id that will be used to match outputs to inputs.
221 pub custom_id: String,
222 pub response: Option<BatchRequestOutputResponse>,
223 /// For requests that failed with a non-HTTP error, this will contain more information on the cause of the failure.
224 pub error: Option<BatchRequestOutputError>,
225}