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