go/resources/files/index.md +0 −655 deleted
File Deleted View Diff
1# Files
2
3## List files
4
5`client.Files.List(ctx, query) (*CursorPage[FileObject], error)`
6
7**get** `/files`
8
9Returns a list of files.
10
11### Parameters
12
13- `query FileListParams`
14
15 - `After param.Field[string]`
16
17 A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
18
19 - `Limit param.Field[int64]`
20
21 A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.
22
23 - `Order param.Field[FileListParamsOrder]`
24
25 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
26
27 - `const FileListParamsOrderAsc FileListParamsOrder = "asc"`
28
29 - `const FileListParamsOrderDesc FileListParamsOrder = "desc"`
30
31 - `Purpose param.Field[string]`
32
33 Only return files with the given purpose.
34
35### Returns
36
37- `type FileObject struct{…}`
38
39 The `File` object represents a document that has been uploaded to OpenAI.
40
41 - `ID string`
42
43 The file identifier, which can be referenced in the API endpoints.
44
45 - `Bytes int64`
46
47 The size of the file, in bytes.
48
49 - `CreatedAt int64`
50
51 The Unix timestamp (in seconds) for when the file was created.
52
53 - `Filename string`
54
55 The name of the file.
56
57 - `Object File`
58
59 The object type, which is always `file`.
60
61 - `const FileFile File = "file"`
62
63 - `Purpose FileObjectPurpose`
64
65 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
66
67 - `const FileObjectPurposeAssistants FileObjectPurpose = "assistants"`
68
69 - `const FileObjectPurposeAssistantsOutput FileObjectPurpose = "assistants_output"`
70
71 - `const FileObjectPurposeBatch FileObjectPurpose = "batch"`
72
73 - `const FileObjectPurposeBatchOutput FileObjectPurpose = "batch_output"`
74
75 - `const FileObjectPurposeFineTune FileObjectPurpose = "fine-tune"`
76
77 - `const FileObjectPurposeFineTuneResults FileObjectPurpose = "fine-tune-results"`
78
79 - `const FileObjectPurposeVision FileObjectPurpose = "vision"`
80
81 - `const FileObjectPurposeUserData FileObjectPurpose = "user_data"`
82
83 - `Status FileObjectStatus`
84
85 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
86
87 - `const FileObjectStatusUploaded FileObjectStatus = "uploaded"`
88
89 - `const FileObjectStatusProcessed FileObjectStatus = "processed"`
90
91 - `const FileObjectStatusError FileObjectStatus = "error"`
92
93 - `ExpiresAt int64`
94
95 The Unix timestamp (in seconds) for when the file will expire.
96
97 - `StatusDetails string`
98
99 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
100
101### Example
102
103```go
104package main
105
106import (
107 "context"
108 "fmt"
109
110 "github.com/openai/openai-go"
111 "github.com/openai/openai-go/option"
112)
113
114func main() {
115 client := openai.NewClient(
116 option.WithAPIKey("My API Key"),
117 )
118 page, err := client.Files.List(context.TODO(), openai.FileListParams{
119
120 })
121 if err != nil {
122 panic(err.Error())
123 }
124 fmt.Printf("%+v\n", page)
125}
126```
127
128#### Response
129
130```json
131{
132 "data": [
133 {
134 "id": "id",
135 "bytes": 0,
136 "created_at": 0,
137 "filename": "filename",
138 "object": "file",
139 "purpose": "assistants",
140 "status": "uploaded",
141 "expires_at": 0,
142 "status_details": "status_details"
143 }
144 ],
145 "first_id": "file-abc123",
146 "has_more": false,
147 "last_id": "file-abc456",
148 "object": "list"
149}
150```
151
152## Upload file
153
154`client.Files.New(ctx, body) (*FileObject, error)`
155
156**post** `/files`
157
158Upload a file that can be used across various endpoints. Individual files
159can be up to 512 MB, and each project can store up to 2.5 TB of files in
160total. There is no organization-wide storage limit. Uploads to this
161endpoint are rate-limited to 1,000 requests per minute per authenticated
162user.
163
164- The Assistants API supports files up to 2 million tokens and of specific
165 file types. See the [Assistants Tools guide](https://platform.openai.com/docs/assistants/tools) for
166 details.
167- The Fine-tuning API only supports `.jsonl` files. The input also has
168 certain required formats for fine-tuning
169 [chat](https://platform.openai.com/docs/api-reference/fine-tuning/chat-input) or
170 [completions](https://platform.openai.com/docs/api-reference/fine-tuning/completions-input) models.
171- The Batch API only supports `.jsonl` files up to 200 MB in size. The input
172 also has a specific required
173 [format](https://platform.openai.com/docs/api-reference/batch/request-input).
174- For Retrieval or `file_search` ingestion, upload files here first. If
175 you need to attach multiple uploaded files to the same vector store, use
176 [`/vector_stores/{vector_store_id}/file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
177 instead of attaching them one by one. Vector store attachment has separate
178 limits from file upload, including 2,000 attached files per minute per
179 organization.
180
181Please [contact us](https://help.openai.com/) if you need to increase these
182storage limits.
183
184### Parameters
185
186- `body FileNewParams`
187
188 - `File param.Field[Reader]`
189
190 The File object (not file name) to be uploaded.
191
192 - `Purpose param.Field[FilePurpose]`
193
194 The intended purpose of the uploaded file. One of:
195
196 - `assistants`: Used in the Assistants API
197 - `batch`: Used in the Batch API
198 - `fine-tune`: Used for fine-tuning
199 - `vision`: Images used for vision fine-tuning
200 - `user_data`: Flexible file type for any purpose
201 - `evals`: Used for eval data sets
202
203 - `ExpiresAfter param.Field[FileNewParamsExpiresAfter]`
204
205 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.
206
207 - `Anchor CreatedAt`
208
209 Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.
210
211 - `const CreatedAtCreatedAt CreatedAt = "created_at"`
212
213 - `Seconds int64`
214
215 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
216
217### Returns
218
219- `type FileObject struct{…}`
220
221 The `File` object represents a document that has been uploaded to OpenAI.
222
223 - `ID string`
224
225 The file identifier, which can be referenced in the API endpoints.
226
227 - `Bytes int64`
228
229 The size of the file, in bytes.
230
231 - `CreatedAt int64`
232
233 The Unix timestamp (in seconds) for when the file was created.
234
235 - `Filename string`
236
237 The name of the file.
238
239 - `Object File`
240
241 The object type, which is always `file`.
242
243 - `const FileFile File = "file"`
244
245 - `Purpose FileObjectPurpose`
246
247 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
248
249 - `const FileObjectPurposeAssistants FileObjectPurpose = "assistants"`
250
251 - `const FileObjectPurposeAssistantsOutput FileObjectPurpose = "assistants_output"`
252
253 - `const FileObjectPurposeBatch FileObjectPurpose = "batch"`
254
255 - `const FileObjectPurposeBatchOutput FileObjectPurpose = "batch_output"`
256
257 - `const FileObjectPurposeFineTune FileObjectPurpose = "fine-tune"`
258
259 - `const FileObjectPurposeFineTuneResults FileObjectPurpose = "fine-tune-results"`
260
261 - `const FileObjectPurposeVision FileObjectPurpose = "vision"`
262
263 - `const FileObjectPurposeUserData FileObjectPurpose = "user_data"`
264
265 - `Status FileObjectStatus`
266
267 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
268
269 - `const FileObjectStatusUploaded FileObjectStatus = "uploaded"`
270
271 - `const FileObjectStatusProcessed FileObjectStatus = "processed"`
272
273 - `const FileObjectStatusError FileObjectStatus = "error"`
274
275 - `ExpiresAt int64`
276
277 The Unix timestamp (in seconds) for when the file will expire.
278
279 - `StatusDetails string`
280
281 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
282
283### Example
284
285```go
286package main
287
288import (
289 "bytes"
290 "context"
291 "fmt"
292 "io"
293
294 "github.com/openai/openai-go"
295 "github.com/openai/openai-go/option"
296)
297
298func main() {
299 client := openai.NewClient(
300 option.WithAPIKey("My API Key"),
301 )
302 fileObject, err := client.Files.New(context.TODO(), openai.FileNewParams{
303 File: io.Reader(bytes.NewBuffer([]byte("Example data"))),
304 Purpose: openai.FilePurposeAssistants,
305 })
306 if err != nil {
307 panic(err.Error())
308 }
309 fmt.Printf("%+v\n", fileObject.ID)
310}
311```
312
313#### Response
314
315```json
316{
317 "id": "id",
318 "bytes": 0,
319 "created_at": 0,
320 "filename": "filename",
321 "object": "file",
322 "purpose": "assistants",
323 "status": "uploaded",
324 "expires_at": 0,
325 "status_details": "status_details"
326}
327```
328
329## Delete file
330
331`client.Files.Delete(ctx, fileID) (*FileDeleted, error)`
332
333**delete** `/files/{file_id}`
334
335Delete a file and remove it from all vector stores.
336
337### Parameters
338
339- `fileID string`
340
341### Returns
342
343- `type FileDeleted struct{…}`
344
345 - `ID string`
346
347 - `Deleted bool`
348
349 - `Object File`
350
351 - `const FileFile File = "file"`
352
353### Example
354
355```go
356package main
357
358import (
359 "context"
360 "fmt"
361
362 "github.com/openai/openai-go"
363 "github.com/openai/openai-go/option"
364)
365
366func main() {
367 client := openai.NewClient(
368 option.WithAPIKey("My API Key"),
369 )
370 fileDeleted, err := client.Files.Delete(context.TODO(), "file_id")
371 if err != nil {
372 panic(err.Error())
373 }
374 fmt.Printf("%+v\n", fileDeleted.ID)
375}
376```
377
378#### Response
379
380```json
381{
382 "id": "id",
383 "deleted": true,
384 "object": "file"
385}
386```
387
388## Retrieve file
389
390`client.Files.Get(ctx, fileID) (*FileObject, error)`
391
392**get** `/files/{file_id}`
393
394Returns information about a specific file.
395
396### Parameters
397
398- `fileID string`
399
400### Returns
401
402- `type FileObject struct{…}`
403
404 The `File` object represents a document that has been uploaded to OpenAI.
405
406 - `ID string`
407
408 The file identifier, which can be referenced in the API endpoints.
409
410 - `Bytes int64`
411
412 The size of the file, in bytes.
413
414 - `CreatedAt int64`
415
416 The Unix timestamp (in seconds) for when the file was created.
417
418 - `Filename string`
419
420 The name of the file.
421
422 - `Object File`
423
424 The object type, which is always `file`.
425
426 - `const FileFile File = "file"`
427
428 - `Purpose FileObjectPurpose`
429
430 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
431
432 - `const FileObjectPurposeAssistants FileObjectPurpose = "assistants"`
433
434 - `const FileObjectPurposeAssistantsOutput FileObjectPurpose = "assistants_output"`
435
436 - `const FileObjectPurposeBatch FileObjectPurpose = "batch"`
437
438 - `const FileObjectPurposeBatchOutput FileObjectPurpose = "batch_output"`
439
440 - `const FileObjectPurposeFineTune FileObjectPurpose = "fine-tune"`
441
442 - `const FileObjectPurposeFineTuneResults FileObjectPurpose = "fine-tune-results"`
443
444 - `const FileObjectPurposeVision FileObjectPurpose = "vision"`
445
446 - `const FileObjectPurposeUserData FileObjectPurpose = "user_data"`
447
448 - `Status FileObjectStatus`
449
450 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
451
452 - `const FileObjectStatusUploaded FileObjectStatus = "uploaded"`
453
454 - `const FileObjectStatusProcessed FileObjectStatus = "processed"`
455
456 - `const FileObjectStatusError FileObjectStatus = "error"`
457
458 - `ExpiresAt int64`
459
460 The Unix timestamp (in seconds) for when the file will expire.
461
462 - `StatusDetails string`
463
464 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
465
466### Example
467
468```go
469package main
470
471import (
472 "context"
473 "fmt"
474
475 "github.com/openai/openai-go"
476 "github.com/openai/openai-go/option"
477)
478
479func main() {
480 client := openai.NewClient(
481 option.WithAPIKey("My API Key"),
482 )
483 fileObject, err := client.Files.Get(context.TODO(), "file_id")
484 if err != nil {
485 panic(err.Error())
486 }
487 fmt.Printf("%+v\n", fileObject.ID)
488}
489```
490
491#### Response
492
493```json
494{
495 "id": "id",
496 "bytes": 0,
497 "created_at": 0,
498 "filename": "filename",
499 "object": "file",
500 "purpose": "assistants",
501 "status": "uploaded",
502 "expires_at": 0,
503 "status_details": "status_details"
504}
505```
506
507## Retrieve file content
508
509`client.Files.Content(ctx, fileID) (*Response, error)`
510
511**get** `/files/{file_id}/content`
512
513Returns the contents of the specified file.
514
515### Parameters
516
517- `fileID string`
518
519### Returns
520
521- `type FileContentResponse interface{…}`
522
523### Example
524
525```go
526package main
527
528import (
529 "context"
530 "fmt"
531
532 "github.com/openai/openai-go"
533 "github.com/openai/openai-go/option"
534)
535
536func main() {
537 client := openai.NewClient(
538 option.WithAPIKey("My API Key"),
539 )
540 response, err := client.Files.Content(context.TODO(), "file_id")
541 if err != nil {
542 panic(err.Error())
543 }
544 fmt.Printf("%+v\n", response)
545}
546```
547
548## Domain Types
549
550### File Content
551
552- `type FileContent string`
553
554### File Deleted
555
556- `type FileDeleted struct{…}`
557
558 - `ID string`
559
560 - `Deleted bool`
561
562 - `Object File`
563
564 - `const FileFile File = "file"`
565
566### File Object
567
568- `type FileObject struct{…}`
569
570 The `File` object represents a document that has been uploaded to OpenAI.
571
572 - `ID string`
573
574 The file identifier, which can be referenced in the API endpoints.
575
576 - `Bytes int64`
577
578 The size of the file, in bytes.
579
580 - `CreatedAt int64`
581
582 The Unix timestamp (in seconds) for when the file was created.
583
584 - `Filename string`
585
586 The name of the file.
587
588 - `Object File`
589
590 The object type, which is always `file`.
591
592 - `const FileFile File = "file"`
593
594 - `Purpose FileObjectPurpose`
595
596 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
597
598 - `const FileObjectPurposeAssistants FileObjectPurpose = "assistants"`
599
600 - `const FileObjectPurposeAssistantsOutput FileObjectPurpose = "assistants_output"`
601
602 - `const FileObjectPurposeBatch FileObjectPurpose = "batch"`
603
604 - `const FileObjectPurposeBatchOutput FileObjectPurpose = "batch_output"`
605
606 - `const FileObjectPurposeFineTune FileObjectPurpose = "fine-tune"`
607
608 - `const FileObjectPurposeFineTuneResults FileObjectPurpose = "fine-tune-results"`
609
610 - `const FileObjectPurposeVision FileObjectPurpose = "vision"`
611
612 - `const FileObjectPurposeUserData FileObjectPurpose = "user_data"`
613
614 - `Status FileObjectStatus`
615
616 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
617
618 - `const FileObjectStatusUploaded FileObjectStatus = "uploaded"`
619
620 - `const FileObjectStatusProcessed FileObjectStatus = "processed"`
621
622 - `const FileObjectStatusError FileObjectStatus = "error"`
623
624 - `ExpiresAt int64`
625
626 The Unix timestamp (in seconds) for when the file will expire.
627
628 - `StatusDetails string`
629
630 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
631
632### File Purpose
633
634- `type FilePurpose string`
635
636 The intended purpose of the uploaded file. One of:
637
638 - `assistants`: Used in the Assistants API
639 - `batch`: Used in the Batch API
640 - `fine-tune`: Used for fine-tuning
641 - `vision`: Images used for vision fine-tuning
642 - `user_data`: Flexible file type for any purpose
643 - `evals`: Used for eval data sets
644
645 - `const FilePurposeAssistants FilePurpose = "assistants"`
646
647 - `const FilePurposeBatch FilePurpose = "batch"`
648
649 - `const FilePurposeFineTune FilePurpose = "fine-tune"`
650
651 - `const FilePurposeVision FilePurpose = "vision"`
652
653 - `const FilePurposeUserData FilePurpose = "user_data"`
654
655 - `const FilePurposeEvals FilePurpose = "evals"`