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