cli/resources/uploads/index.md +0 −730 deleted
File Deleted View Diff
1# Uploads
2
3## Create upload
4
5`$ openai uploads create`
6
7**post** `/uploads`
8
9Creates an intermediate [Upload](https://platform.openai.com/docs/api-reference/uploads/object) object
10that you can add [Parts](https://platform.openai.com/docs/api-reference/uploads/part-object) to.
11Currently, an Upload can accept at most 8 GB in total and expires after an
12hour after you create it.
13
14Once you complete the Upload, we will create a
15[File](https://platform.openai.com/docs/api-reference/files/object) object that contains all the parts
16you uploaded. This File is usable in the rest of our platform as a regular
17File object.
18
19For certain `purpose` values, the correct `mime_type` must be specified.
20Please refer to documentation for the
21[supported MIME types for your use case](https://platform.openai.com/docs/assistants/tools/file-search#supported-files).
22
23For guidance on the proper filename extensions for each purpose, please
24follow the documentation on [creating a
25File](https://platform.openai.com/docs/api-reference/files/create).
26
27Returns the Upload object with status `pending`.
28
29### Parameters
30
31- `--bytes: number`
32
33 The number of bytes in the file you are uploading.
34
35- `--filename: string`
36
37 The name of the file to upload.
38
39- `--mime-type: string`
40
41 The MIME type of the file.
42
43 This must fall within the supported MIME types for your file purpose. See
44 the supported MIME types for assistants and vision.
45
46- `--purpose: "assistants" or "batch" or "fine-tune" or 3 more`
47
48 The intended purpose of the uploaded file.
49
50 See the [documentation on File
51 purposes](https://platform.openai.com/docs/api-reference/files/create#files-create-purpose).
52
53- `--expires-after: optional object { anchor, seconds }`
54
55 The expiration policy for a file. By default, files with `purpose=batch` expire after 30 days and all other files are persisted until they are manually deleted.
56
57### Returns
58
59- `upload: object { id, bytes, created_at, 6 more }`
60
61 The Upload object can accept byte chunks in the form of Parts.
62
63 - `id: string`
64
65 The Upload unique identifier, which can be referenced in API endpoints.
66
67 - `bytes: number`
68
69 The intended number of bytes to be uploaded.
70
71 - `created_at: number`
72
73 The Unix timestamp (in seconds) for when the Upload was created.
74
75 - `expires_at: number`
76
77 The Unix timestamp (in seconds) for when the Upload will expire.
78
79 - `filename: string`
80
81 The name of the file to be uploaded.
82
83 - `object: "upload"`
84
85 The object type, which is always "upload".
86
87 - `purpose: string`
88
89 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.
90
91 - `status: "pending" or "completed" or "cancelled" or "expired"`
92
93 The status of the Upload.
94
95 - `"pending"`
96
97 - `"completed"`
98
99 - `"cancelled"`
100
101 - `"expired"`
102
103 - `file: optional object { id, bytes, created_at, 6 more }`
104
105 The `File` object represents a document that has been uploaded to OpenAI.
106
107 - `id: string`
108
109 The file identifier, which can be referenced in the API endpoints.
110
111 - `bytes: number`
112
113 The size of the file, in bytes.
114
115 - `created_at: number`
116
117 The Unix timestamp (in seconds) for when the file was created.
118
119 - `filename: string`
120
121 The name of the file.
122
123 - `object: "file"`
124
125 The object type, which is always `file`.
126
127 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
128
129 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
130
131 - `"assistants"`
132
133 - `"assistants_output"`
134
135 - `"batch"`
136
137 - `"batch_output"`
138
139 - `"fine-tune"`
140
141 - `"fine-tune-results"`
142
143 - `"vision"`
144
145 - `"user_data"`
146
147 - `status: "uploaded" or "processed" or "error"`
148
149 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
150
151 - `"uploaded"`
152
153 - `"processed"`
154
155 - `"error"`
156
157 - `expires_at: optional number`
158
159 The Unix timestamp (in seconds) for when the file will expire.
160
161 - `status_details: optional string`
162
163 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
164
165### Example
166
167```cli
168openai uploads create \
169 --api-key 'My API Key' \
170 --bytes 0 \
171 --filename filename \
172 --mime-type mime_type \
173 --purpose assistants
174```
175
176#### Response
177
178```json
179{
180 "id": "id",
181 "bytes": 0,
182 "created_at": 0,
183 "expires_at": 0,
184 "filename": "filename",
185 "object": "upload",
186 "purpose": "purpose",
187 "status": "pending",
188 "file": {
189 "id": "id",
190 "bytes": 0,
191 "created_at": 0,
192 "filename": "filename",
193 "object": "file",
194 "purpose": "assistants",
195 "status": "uploaded",
196 "expires_at": 0,
197 "status_details": "status_details"
198 }
199}
200```
201
202## Complete upload
203
204`$ openai uploads complete`
205
206**post** `/uploads/{upload_id}/complete`
207
208Completes the [Upload](https://platform.openai.com/docs/api-reference/uploads/object).
209
210Within the returned Upload object, there is a nested [File](https://platform.openai.com/docs/api-reference/files/object) object that is ready to use in the rest of the platform.
211
212You can specify the order of the Parts by passing in an ordered list of the Part IDs.
213
214The number of bytes uploaded upon completion must match the number of bytes initially specified when creating the Upload object. No Parts may be added after an Upload is completed.
215Returns the Upload object with status `completed`, including an additional `file` property containing the created usable File object.
216
217### Parameters
218
219- `--upload-id: string`
220
221 The ID of the Upload.
222
223- `--part-id: array of string`
224
225 The ordered list of Part IDs.
226
227- `--md5: optional string`
228
229 The optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.
230
231### Returns
232
233- `upload: object { id, bytes, created_at, 6 more }`
234
235 The Upload object can accept byte chunks in the form of Parts.
236
237 - `id: string`
238
239 The Upload unique identifier, which can be referenced in API endpoints.
240
241 - `bytes: number`
242
243 The intended number of bytes to be uploaded.
244
245 - `created_at: number`
246
247 The Unix timestamp (in seconds) for when the Upload was created.
248
249 - `expires_at: number`
250
251 The Unix timestamp (in seconds) for when the Upload will expire.
252
253 - `filename: string`
254
255 The name of the file to be uploaded.
256
257 - `object: "upload"`
258
259 The object type, which is always "upload".
260
261 - `purpose: string`
262
263 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.
264
265 - `status: "pending" or "completed" or "cancelled" or "expired"`
266
267 The status of the Upload.
268
269 - `"pending"`
270
271 - `"completed"`
272
273 - `"cancelled"`
274
275 - `"expired"`
276
277 - `file: optional object { id, bytes, created_at, 6 more }`
278
279 The `File` object represents a document that has been uploaded to OpenAI.
280
281 - `id: string`
282
283 The file identifier, which can be referenced in the API endpoints.
284
285 - `bytes: number`
286
287 The size of the file, in bytes.
288
289 - `created_at: number`
290
291 The Unix timestamp (in seconds) for when the file was created.
292
293 - `filename: string`
294
295 The name of the file.
296
297 - `object: "file"`
298
299 The object type, which is always `file`.
300
301 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
302
303 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
304
305 - `"assistants"`
306
307 - `"assistants_output"`
308
309 - `"batch"`
310
311 - `"batch_output"`
312
313 - `"fine-tune"`
314
315 - `"fine-tune-results"`
316
317 - `"vision"`
318
319 - `"user_data"`
320
321 - `status: "uploaded" or "processed" or "error"`
322
323 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
324
325 - `"uploaded"`
326
327 - `"processed"`
328
329 - `"error"`
330
331 - `expires_at: optional number`
332
333 The Unix timestamp (in seconds) for when the file will expire.
334
335 - `status_details: optional string`
336
337 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
338
339### Example
340
341```cli
342openai uploads complete \
343 --api-key 'My API Key' \
344 --upload-id upload_abc123 \
345 --part-id string
346```
347
348#### Response
349
350```json
351{
352 "id": "id",
353 "bytes": 0,
354 "created_at": 0,
355 "expires_at": 0,
356 "filename": "filename",
357 "object": "upload",
358 "purpose": "purpose",
359 "status": "pending",
360 "file": {
361 "id": "id",
362 "bytes": 0,
363 "created_at": 0,
364 "filename": "filename",
365 "object": "file",
366 "purpose": "assistants",
367 "status": "uploaded",
368 "expires_at": 0,
369 "status_details": "status_details"
370 }
371}
372```
373
374## Cancel upload
375
376`$ openai uploads cancel`
377
378**post** `/uploads/{upload_id}/cancel`
379
380Cancels the Upload. No Parts may be added after an Upload is cancelled.
381
382Returns the Upload object with status `cancelled`.
383
384### Parameters
385
386- `--upload-id: string`
387
388 The ID of the Upload.
389
390### Returns
391
392- `upload: object { id, bytes, created_at, 6 more }`
393
394 The Upload object can accept byte chunks in the form of Parts.
395
396 - `id: string`
397
398 The Upload unique identifier, which can be referenced in API endpoints.
399
400 - `bytes: number`
401
402 The intended number of bytes to be uploaded.
403
404 - `created_at: number`
405
406 The Unix timestamp (in seconds) for when the Upload was created.
407
408 - `expires_at: number`
409
410 The Unix timestamp (in seconds) for when the Upload will expire.
411
412 - `filename: string`
413
414 The name of the file to be uploaded.
415
416 - `object: "upload"`
417
418 The object type, which is always "upload".
419
420 - `purpose: string`
421
422 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.
423
424 - `status: "pending" or "completed" or "cancelled" or "expired"`
425
426 The status of the Upload.
427
428 - `"pending"`
429
430 - `"completed"`
431
432 - `"cancelled"`
433
434 - `"expired"`
435
436 - `file: optional object { id, bytes, created_at, 6 more }`
437
438 The `File` object represents a document that has been uploaded to OpenAI.
439
440 - `id: string`
441
442 The file identifier, which can be referenced in the API endpoints.
443
444 - `bytes: number`
445
446 The size of the file, in bytes.
447
448 - `created_at: number`
449
450 The Unix timestamp (in seconds) for when the file was created.
451
452 - `filename: string`
453
454 The name of the file.
455
456 - `object: "file"`
457
458 The object type, which is always `file`.
459
460 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
461
462 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
463
464 - `"assistants"`
465
466 - `"assistants_output"`
467
468 - `"batch"`
469
470 - `"batch_output"`
471
472 - `"fine-tune"`
473
474 - `"fine-tune-results"`
475
476 - `"vision"`
477
478 - `"user_data"`
479
480 - `status: "uploaded" or "processed" or "error"`
481
482 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
483
484 - `"uploaded"`
485
486 - `"processed"`
487
488 - `"error"`
489
490 - `expires_at: optional number`
491
492 The Unix timestamp (in seconds) for when the file will expire.
493
494 - `status_details: optional string`
495
496 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
497
498### Example
499
500```cli
501openai uploads cancel \
502 --api-key 'My API Key' \
503 --upload-id upload_abc123
504```
505
506#### Response
507
508```json
509{
510 "id": "id",
511 "bytes": 0,
512 "created_at": 0,
513 "expires_at": 0,
514 "filename": "filename",
515 "object": "upload",
516 "purpose": "purpose",
517 "status": "pending",
518 "file": {
519 "id": "id",
520 "bytes": 0,
521 "created_at": 0,
522 "filename": "filename",
523 "object": "file",
524 "purpose": "assistants",
525 "status": "uploaded",
526 "expires_at": 0,
527 "status_details": "status_details"
528 }
529}
530```
531
532## Domain Types
533
534### Upload
535
536- `upload: object { id, bytes, created_at, 6 more }`
537
538 The Upload object can accept byte chunks in the form of Parts.
539
540 - `id: string`
541
542 The Upload unique identifier, which can be referenced in API endpoints.
543
544 - `bytes: number`
545
546 The intended number of bytes to be uploaded.
547
548 - `created_at: number`
549
550 The Unix timestamp (in seconds) for when the Upload was created.
551
552 - `expires_at: number`
553
554 The Unix timestamp (in seconds) for when the Upload will expire.
555
556 - `filename: string`
557
558 The name of the file to be uploaded.
559
560 - `object: "upload"`
561
562 The object type, which is always "upload".
563
564 - `purpose: string`
565
566 The intended purpose of the file. [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) for acceptable values.
567
568 - `status: "pending" or "completed" or "cancelled" or "expired"`
569
570 The status of the Upload.
571
572 - `"pending"`
573
574 - `"completed"`
575
576 - `"cancelled"`
577
578 - `"expired"`
579
580 - `file: optional object { id, bytes, created_at, 6 more }`
581
582 The `File` object represents a document that has been uploaded to OpenAI.
583
584 - `id: string`
585
586 The file identifier, which can be referenced in the API endpoints.
587
588 - `bytes: number`
589
590 The size of the file, in bytes.
591
592 - `created_at: number`
593
594 The Unix timestamp (in seconds) for when the file was created.
595
596 - `filename: string`
597
598 The name of the file.
599
600 - `object: "file"`
601
602 The object type, which is always `file`.
603
604 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
605
606 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
607
608 - `"assistants"`
609
610 - `"assistants_output"`
611
612 - `"batch"`
613
614 - `"batch_output"`
615
616 - `"fine-tune"`
617
618 - `"fine-tune-results"`
619
620 - `"vision"`
621
622 - `"user_data"`
623
624 - `status: "uploaded" or "processed" or "error"`
625
626 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
627
628 - `"uploaded"`
629
630 - `"processed"`
631
632 - `"error"`
633
634 - `expires_at: optional number`
635
636 The Unix timestamp (in seconds) for when the file will expire.
637
638 - `status_details: optional string`
639
640 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
641
642# Parts
643
644## Add upload part
645
646`$ openai uploads:parts create`
647
648**post** `/uploads/{upload_id}/parts`
649
650Adds a [Part](https://platform.openai.com/docs/api-reference/uploads/part-object) to an [Upload](https://platform.openai.com/docs/api-reference/uploads/object) object. A Part represents a chunk of bytes from the file you are trying to upload.
651
652Each Part can be at most 64 MB, and you can add Parts until you hit the Upload maximum of 8 GB.
653
654It is possible to add multiple Parts in parallel. You can decide the intended order of the Parts when you [complete the Upload](https://platform.openai.com/docs/api-reference/uploads/complete).
655
656### Parameters
657
658- `--upload-id: string`
659
660 The ID of the Upload.
661
662- `--data: string`
663
664 The chunk of bytes for this Part.
665
666### Returns
667
668- `upload_part: object { id, created_at, object, upload_id }`
669
670 The upload Part represents a chunk of bytes we can add to an Upload object.
671
672 - `id: string`
673
674 The upload Part unique identifier, which can be referenced in API endpoints.
675
676 - `created_at: number`
677
678 The Unix timestamp (in seconds) for when the Part was created.
679
680 - `object: "upload.part"`
681
682 The object type, which is always `upload.part`.
683
684 - `upload_id: string`
685
686 The ID of the Upload object that this Part was added to.
687
688### Example
689
690```cli
691openai uploads:parts create \
692 --api-key 'My API Key' \
693 --upload-id upload_abc123 \
694 --data 'Example data'
695```
696
697#### Response
698
699```json
700{
701 "id": "id",
702 "created_at": 0,
703 "object": "upload.part",
704 "upload_id": "upload_id"
705}
706```
707
708## Domain Types
709
710### Upload Part
711
712- `upload_part: object { id, created_at, object, upload_id }`
713
714 The upload Part represents a chunk of bytes we can add to an Upload object.
715
716 - `id: string`
717
718 The upload Part unique identifier, which can be referenced in API endpoints.
719
720 - `created_at: number`
721
722 The Unix timestamp (in seconds) for when the Part was created.
723
724 - `object: "upload.part"`
725
726 The object type, which is always `upload.part`.
727
728 - `upload_id: string`
729
730 The ID of the Upload object that this Part was added to.