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