java/resources/batches/methods/create/index.md +0 −328 deleted
File Deleted View Diff
1## Create batch
2
3`Batch batches().create(BatchCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`
4
5**post** `/batches`
6
7Creates and executes a batch from an uploaded file of requests
8
9### Parameters
10
11- `BatchCreateParams params`
12
13 - `CompletionWindow completionWindow`
14
15 The time frame within which the batch should be processed. Currently only `24h` is supported.
16
17 - `_24H("24h")`
18
19 - `Endpoint endpoint`
20
21 The endpoint to be used for all requests in the batch. Currently `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/completions`, `/v1/moderations`, `/v1/images/generations`, `/v1/images/edits`, and `/v1/videos` are supported. Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
22
23 - `V1_RESPONSES("/v1/responses")`
24
25 - `V1_CHAT_COMPLETIONS("/v1/chat/completions")`
26
27 - `V1_EMBEDDINGS("/v1/embeddings")`
28
29 - `V1_COMPLETIONS("/v1/completions")`
30
31 - `V1_MODERATIONS("/v1/moderations")`
32
33 - `V1_IMAGES_GENERATIONS("/v1/images/generations")`
34
35 - `V1_IMAGES_EDITS("/v1/images/edits")`
36
37 - `V1_VIDEOS("/v1/videos")`
38
39 - `String inputFileId`
40
41 The ID of an uploaded file that contains requests for the new batch.
42
43 See [upload file](https://platform.openai.com/docs/api-reference/files/create) for how to upload a file.
44
45 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.
46
47 - `Optional<Metadata> metadata`
48
49 Set of 16 key-value pairs that can be attached to an object. This can be
50 useful for storing additional information about the object in a structured
51 format, and querying for objects via API or the dashboard.
52
53 Keys are strings with a maximum length of 64 characters. Values are strings
54 with a maximum length of 512 characters.
55
56 - `Optional<OutputExpiresAfter> outputExpiresAfter`
57
58 The expiration policy for the output and/or error file that are generated for a batch.
59
60 - `JsonValue; anchor "created_at"constant`
61
62 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.
63
64 - `CREATED_AT("created_at")`
65
66 - `long seconds`
67
68 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
69
70### Returns
71
72- `class Batch:`
73
74 - `String id`
75
76 - `String completionWindow`
77
78 The time frame within which the batch should be processed.
79
80 - `long createdAt`
81
82 The Unix timestamp (in seconds) for when the batch was created.
83
84 - `String endpoint`
85
86 The OpenAI API endpoint used by the batch.
87
88 - `String inputFileId`
89
90 The ID of the input file for the batch.
91
92 - `JsonValue; object_ "batch"constant`
93
94 The object type, which is always `batch`.
95
96 - `BATCH("batch")`
97
98 - `Status status`
99
100 The current status of the batch.
101
102 - `VALIDATING("validating")`
103
104 - `FAILED("failed")`
105
106 - `IN_PROGRESS("in_progress")`
107
108 - `FINALIZING("finalizing")`
109
110 - `COMPLETED("completed")`
111
112 - `EXPIRED("expired")`
113
114 - `CANCELLING("cancelling")`
115
116 - `CANCELLED("cancelled")`
117
118 - `Optional<Long> cancelledAt`
119
120 The Unix timestamp (in seconds) for when the batch was cancelled.
121
122 - `Optional<Long> cancellingAt`
123
124 The Unix timestamp (in seconds) for when the batch started cancelling.
125
126 - `Optional<Long> completedAt`
127
128 The Unix timestamp (in seconds) for when the batch was completed.
129
130 - `Optional<String> errorFileId`
131
132 The ID of the file containing the outputs of requests with errors.
133
134 - `Optional<Errors> errors`
135
136 - `Optional<List<BatchError>> data`
137
138 - `Optional<String> code`
139
140 An error code identifying the error type.
141
142 - `Optional<Long> line`
143
144 The line number of the input file where the error occurred, if applicable.
145
146 - `Optional<String> message`
147
148 A human-readable message providing more details about the error.
149
150 - `Optional<String> param`
151
152 The name of the parameter that caused the error, if applicable.
153
154 - `Optional<String> object_`
155
156 The object type, which is always `list`.
157
158 - `Optional<Long> expiredAt`
159
160 The Unix timestamp (in seconds) for when the batch expired.
161
162 - `Optional<Long> expiresAt`
163
164 The Unix timestamp (in seconds) for when the batch will expire.
165
166 - `Optional<Long> failedAt`
167
168 The Unix timestamp (in seconds) for when the batch failed.
169
170 - `Optional<Long> finalizingAt`
171
172 The Unix timestamp (in seconds) for when the batch started finalizing.
173
174 - `Optional<Long> inProgressAt`
175
176 The Unix timestamp (in seconds) for when the batch started processing.
177
178 - `Optional<Metadata> metadata`
179
180 Set of 16 key-value pairs that can be attached to an object. This can be
181 useful for storing additional information about the object in a structured
182 format, and querying for objects via API or the dashboard.
183
184 Keys are strings with a maximum length of 64 characters. Values are strings
185 with a maximum length of 512 characters.
186
187 - `Optional<String> model`
188
189 Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
190 offers a wide range of models with different capabilities, performance
191 characteristics, and price points. Refer to the [model
192 guide](https://platform.openai.com/docs/models) to browse and compare available models.
193
194 - `Optional<String> outputFileId`
195
196 The ID of the file containing the outputs of successfully executed requests.
197
198 - `Optional<BatchRequestCounts> requestCounts`
199
200 The request counts for different statuses within the batch.
201
202 - `long completed`
203
204 Number of requests that have been completed successfully.
205
206 - `long failed`
207
208 Number of requests that have failed.
209
210 - `long total`
211
212 Total number of requests in the batch.
213
214 - `Optional<BatchUsage> usage`
215
216 Represents token usage details including input tokens, output tokens, a
217 breakdown of output tokens, and the total tokens used. Only populated on
218 batches created after September 7, 2025.
219
220 - `long inputTokens`
221
222 The number of input tokens.
223
224 - `InputTokensDetails inputTokensDetails`
225
226 A detailed breakdown of the input tokens.
227
228 - `long cachedTokens`
229
230 The number of tokens that were retrieved from the cache. [More on
231 prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
232
233 - `long outputTokens`
234
235 The number of output tokens.
236
237 - `OutputTokensDetails outputTokensDetails`
238
239 A detailed breakdown of the output tokens.
240
241 - `long reasoningTokens`
242
243 The number of reasoning tokens.
244
245 - `long totalTokens`
246
247 The total number of tokens used.
248
249### Example
250
251```java
252package com.openai.example;
253
254import com.openai.client.OpenAIClient;
255import com.openai.client.okhttp.OpenAIOkHttpClient;
256import com.openai.models.batches.Batch;
257import com.openai.models.batches.BatchCreateParams;
258
259public final class Main {
260 private Main() {}
261
262 public static void main(String[] args) {
263 OpenAIClient client = OpenAIOkHttpClient.fromEnv();
264
265 BatchCreateParams params = BatchCreateParams.builder()
266 .completionWindow(BatchCreateParams.CompletionWindow._24H)
267 .endpoint(BatchCreateParams.Endpoint.V1_RESPONSES)
268 .inputFileId("input_file_id")
269 .build();
270 Batch batch = client.batches().create(params);
271 }
272}
273```
274
275#### Response
276
277```json
278{
279 "id": "id",
280 "completion_window": "completion_window",
281 "created_at": 0,
282 "endpoint": "endpoint",
283 "input_file_id": "input_file_id",
284 "object": "batch",
285 "status": "validating",
286 "cancelled_at": 0,
287 "cancelling_at": 0,
288 "completed_at": 0,
289 "error_file_id": "error_file_id",
290 "errors": {
291 "data": [
292 {
293 "code": "code",
294 "line": 0,
295 "message": "message",
296 "param": "param"
297 }
298 ],
299 "object": "object"
300 },
301 "expired_at": 0,
302 "expires_at": 0,
303 "failed_at": 0,
304 "finalizing_at": 0,
305 "in_progress_at": 0,
306 "metadata": {
307 "foo": "string"
308 },
309 "model": "model",
310 "output_file_id": "output_file_id",
311 "request_counts": {
312 "completed": 0,
313 "failed": 0,
314 "total": 0
315 },
316 "usage": {
317 "input_tokens": 0,
318 "input_tokens_details": {
319 "cached_tokens": 0
320 },
321 "output_tokens": 0,
322 "output_tokens_details": {
323 "reasoning_tokens": 0
324 },
325 "total_tokens": 0
326 }
327}
328```