go/resources/batches/methods/create/index.md +0 −331 deleted
File Deleted View Diff
1## Create batch
2
3`client.Batches.New(ctx, body) (*Batch, error)`
4
5**post** `/batches`
6
7Creates and executes a batch from an uploaded file of requests
8
9### Parameters
10
11- `body BatchNewParams`
12
13 - `CompletionWindow param.Field[BatchNewParamsCompletionWindow]`
14
15 The time frame within which the batch should be processed. Currently only `24h` is supported.
16
17 - `const BatchNewParamsCompletionWindow24h BatchNewParamsCompletionWindow = "24h"`
18
19 - `Endpoint param.Field[BatchNewParamsEndpoint]`
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 - `const BatchNewParamsEndpointV1Responses BatchNewParamsEndpoint = "/v1/responses"`
24
25 - `const BatchNewParamsEndpointV1ChatCompletions BatchNewParamsEndpoint = "/v1/chat/completions"`
26
27 - `const BatchNewParamsEndpointV1Embeddings BatchNewParamsEndpoint = "/v1/embeddings"`
28
29 - `const BatchNewParamsEndpointV1Completions BatchNewParamsEndpoint = "/v1/completions"`
30
31 - `const BatchNewParamsEndpointV1Moderations BatchNewParamsEndpoint = "/v1/moderations"`
32
33 - `const BatchNewParamsEndpointV1ImagesGenerations BatchNewParamsEndpoint = "/v1/images/generations"`
34
35 - `const BatchNewParamsEndpointV1ImagesEdits BatchNewParamsEndpoint = "/v1/images/edits"`
36
37 - `const BatchNewParamsEndpointV1Videos BatchNewParamsEndpoint = "/v1/videos"`
38
39 - `InputFileID param.Field[string]`
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 - `Metadata param.Field[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 - `OutputExpiresAfter param.Field[BatchNewParamsOutputExpiresAfter]`
57
58 The expiration policy for the output and/or error file that are generated for a batch.
59
60 - `Anchor CreatedAt`
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 - `const CreatedAtCreatedAt CreatedAt = "created_at"`
65
66 - `Seconds int64`
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- `type Batch struct{…}`
73
74 - `ID string`
75
76 - `CompletionWindow string`
77
78 The time frame within which the batch should be processed.
79
80 - `CreatedAt int64`
81
82 The Unix timestamp (in seconds) for when the batch was created.
83
84 - `Endpoint string`
85
86 The OpenAI API endpoint used by the batch.
87
88 - `InputFileID string`
89
90 The ID of the input file for the batch.
91
92 - `Object Batch`
93
94 The object type, which is always `batch`.
95
96 - `const BatchBatch Batch = "batch"`
97
98 - `Status BatchStatus`
99
100 The current status of the batch.
101
102 - `const BatchStatusValidating BatchStatus = "validating"`
103
104 - `const BatchStatusFailed BatchStatus = "failed"`
105
106 - `const BatchStatusInProgress BatchStatus = "in_progress"`
107
108 - `const BatchStatusFinalizing BatchStatus = "finalizing"`
109
110 - `const BatchStatusCompleted BatchStatus = "completed"`
111
112 - `const BatchStatusExpired BatchStatus = "expired"`
113
114 - `const BatchStatusCancelling BatchStatus = "cancelling"`
115
116 - `const BatchStatusCancelled BatchStatus = "cancelled"`
117
118 - `CancelledAt int64`
119
120 The Unix timestamp (in seconds) for when the batch was cancelled.
121
122 - `CancellingAt int64`
123
124 The Unix timestamp (in seconds) for when the batch started cancelling.
125
126 - `CompletedAt int64`
127
128 The Unix timestamp (in seconds) for when the batch was completed.
129
130 - `ErrorFileID string`
131
132 The ID of the file containing the outputs of requests with errors.
133
134 - `Errors BatchErrors`
135
136 - `Data []BatchError`
137
138 - `Code string`
139
140 An error code identifying the error type.
141
142 - `Line int64`
143
144 The line number of the input file where the error occurred, if applicable.
145
146 - `Message string`
147
148 A human-readable message providing more details about the error.
149
150 - `Param string`
151
152 The name of the parameter that caused the error, if applicable.
153
154 - `Object string`
155
156 The object type, which is always `list`.
157
158 - `ExpiredAt int64`
159
160 The Unix timestamp (in seconds) for when the batch expired.
161
162 - `ExpiresAt int64`
163
164 The Unix timestamp (in seconds) for when the batch will expire.
165
166 - `FailedAt int64`
167
168 The Unix timestamp (in seconds) for when the batch failed.
169
170 - `FinalizingAt int64`
171
172 The Unix timestamp (in seconds) for when the batch started finalizing.
173
174 - `InProgressAt int64`
175
176 The Unix timestamp (in seconds) for when the batch started processing.
177
178 - `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 - `Model string`
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 - `OutputFileID string`
195
196 The ID of the file containing the outputs of successfully executed requests.
197
198 - `RequestCounts BatchRequestCounts`
199
200 The request counts for different statuses within the batch.
201
202 - `Completed int64`
203
204 Number of requests that have been completed successfully.
205
206 - `Failed int64`
207
208 Number of requests that have failed.
209
210 - `Total int64`
211
212 Total number of requests in the batch.
213
214 - `Usage BatchUsage`
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 - `InputTokens int64`
221
222 The number of input tokens.
223
224 - `InputTokensDetails BatchUsageInputTokensDetails`
225
226 A detailed breakdown of the input tokens.
227
228 - `CachedTokens int64`
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 - `OutputTokens int64`
234
235 The number of output tokens.
236
237 - `OutputTokensDetails BatchUsageOutputTokensDetails`
238
239 A detailed breakdown of the output tokens.
240
241 - `ReasoningTokens int64`
242
243 The number of reasoning tokens.
244
245 - `TotalTokens int64`
246
247 The total number of tokens used.
248
249### Example
250
251```go
252package main
253
254import (
255 "context"
256 "fmt"
257
258 "github.com/openai/openai-go"
259 "github.com/openai/openai-go/option"
260)
261
262func main() {
263 client := openai.NewClient(
264 option.WithAPIKey("My API Key"),
265 )
266 batch, err := client.Batches.New(context.TODO(), openai.BatchNewParams{
267 CompletionWindow: openai.BatchNewParamsCompletionWindow24h,
268 Endpoint: openai.BatchNewParamsEndpointV1Responses,
269 InputFileID: "input_file_id",
270 })
271 if err != nil {
272 panic(err.Error())
273 }
274 fmt.Printf("%+v\n", batch.ID)
275}
276```
277
278#### Response
279
280```json
281{
282 "id": "id",
283 "completion_window": "completion_window",
284 "created_at": 0,
285 "endpoint": "endpoint",
286 "input_file_id": "input_file_id",
287 "object": "batch",
288 "status": "validating",
289 "cancelled_at": 0,
290 "cancelling_at": 0,
291 "completed_at": 0,
292 "error_file_id": "error_file_id",
293 "errors": {
294 "data": [
295 {
296 "code": "code",
297 "line": 0,
298 "message": "message",
299 "param": "param"
300 }
301 ],
302 "object": "object"
303 },
304 "expired_at": 0,
305 "expires_at": 0,
306 "failed_at": 0,
307 "finalizing_at": 0,
308 "in_progress_at": 0,
309 "metadata": {
310 "foo": "string"
311 },
312 "model": "model",
313 "output_file_id": "output_file_id",
314 "request_counts": {
315 "completed": 0,
316 "failed": 0,
317 "total": 0
318 },
319 "usage": {
320 "input_tokens": 0,
321 "input_tokens_details": {
322 "cached_tokens": 0
323 },
324 "output_tokens": 0,
325 "output_tokens_details": {
326 "reasoning_tokens": 0
327 },
328 "total_tokens": 0
329 }
330}
331```