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