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