python/resources/files/index.md +0 −775 deleted
File Deleted View Diff
1# Files
2
3## List files
4
5`files.list(FileListParams**kwargs) -> SyncCursorPage[FileObject]`
6
7**get** `/files`
8
9Returns a list of files.
10
11### Parameters
12
13- `after: Optional[str]`
14
15 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.
16
17- `limit: Optional[int]`
18
19 A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.
20
21- `order: Optional[Literal["asc", "desc"]]`
22
23 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
24
25 - `"asc"`
26
27 - `"desc"`
28
29- `purpose: Optional[str]`
30
31 Only return files with the given purpose.
32
33### Returns
34
35- `class FileObject: …`
36
37 The `File` object represents a document that has been uploaded to OpenAI.
38
39 - `id: str`
40
41 The file identifier, which can be referenced in the API endpoints.
42
43 - `bytes: int`
44
45 The size of the file, in bytes.
46
47 - `created_at: int`
48
49 The Unix timestamp (in seconds) for when the file was created.
50
51 - `filename: str`
52
53 The name of the file.
54
55 - `object: Literal["file"]`
56
57 The object type, which is always `file`.
58
59 - `"file"`
60
61 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`
62
63 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
64
65 - `"assistants"`
66
67 - `"assistants_output"`
68
69 - `"batch"`
70
71 - `"batch_output"`
72
73 - `"fine-tune"`
74
75 - `"fine-tune-results"`
76
77 - `"vision"`
78
79 - `"user_data"`
80
81 - `status: Literal["uploaded", "processed", "error"]`
82
83 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
84
85 - `"uploaded"`
86
87 - `"processed"`
88
89 - `"error"`
90
91 - `expires_at: Optional[int]`
92
93 The Unix timestamp (in seconds) for when the file will expire.
94
95 - `status_details: Optional[str]`
96
97 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
98
99### Example
100
101```python
102import os
103from openai import OpenAI
104
105client = OpenAI(
106 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
107)
108page = client.files.list()
109page = page.data[0]
110print(page)
111```
112
113#### Response
114
115```json
116{
117 "data": [
118 {
119 "id": "id",
120 "bytes": 0,
121 "created_at": 0,
122 "filename": "filename",
123 "object": "file",
124 "purpose": "assistants",
125 "status": "uploaded",
126 "expires_at": 0,
127 "status_details": "status_details"
128 }
129 ],
130 "first_id": "file-abc123",
131 "has_more": false,
132 "last_id": "file-abc456",
133 "object": "list"
134}
135```
136
137### Example
138
139```python
140from openai import OpenAI
141client = OpenAI()
142
143client.files.list()
144```
145
146#### Response
147
148```json
149{
150 "object": "list",
151 "data": [
152 {
153 "id": "file-abc123",
154 "object": "file",
155 "bytes": 175,
156 "created_at": 1613677385,
157 "expires_at": 1677614202,
158 "filename": "salesOverview.pdf",
159 "purpose": "assistants",
160 },
161 {
162 "id": "file-abc456",
163 "object": "file",
164 "bytes": 140,
165 "created_at": 1613779121,
166 "expires_at": 1677614202,
167 "filename": "puppy.jsonl",
168 "purpose": "fine-tune",
169 }
170 ],
171 "first_id": "file-abc123",
172 "last_id": "file-abc456",
173 "has_more": false
174}
175```
176
177## Upload file
178
179`files.create(FileCreateParams**kwargs) -> FileObject`
180
181**post** `/files`
182
183Upload a file that can be used across various endpoints. Individual files
184can be up to 512 MB, and each project can store up to 2.5 TB of files in
185total. There is no organization-wide storage limit. Uploads to this
186endpoint are rate-limited to 1,000 requests per minute per authenticated
187user.
188
189- The Assistants API supports files up to 2 million tokens and of specific
190 file types. See the [Assistants Tools guide](https://platform.openai.com/docs/assistants/tools) for
191 details.
192- The Fine-tuning API only supports `.jsonl` files. The input also has
193 certain required formats for fine-tuning
194 [chat](https://platform.openai.com/docs/api-reference/fine-tuning/chat-input) or
195 [completions](https://platform.openai.com/docs/api-reference/fine-tuning/completions-input) models.
196- The Batch API only supports `.jsonl` files up to 200 MB in size. The input
197 also has a specific required
198 [format](https://platform.openai.com/docs/api-reference/batch/request-input).
199- For Retrieval or `file_search` ingestion, upload files here first. If
200 you need to attach multiple uploaded files to the same vector store, use
201 [`/vector_stores/{vector_store_id}/file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
202 instead of attaching them one by one. Vector store attachment has separate
203 limits from file upload, including 2,000 attached files per minute per
204 organization.
205
206Please [contact us](https://help.openai.com/) if you need to increase these
207storage limits.
208
209### Parameters
210
211- `file: FileTypes`
212
213 The File object (not file name) to be uploaded.
214
215- `purpose: FilePurpose`
216
217 The intended purpose of the uploaded file. One of:
218
219 - `assistants`: Used in the Assistants API
220 - `batch`: Used in the Batch API
221 - `fine-tune`: Used for fine-tuning
222 - `vision`: Images used for vision fine-tuning
223 - `user_data`: Flexible file type for any purpose
224 - `evals`: Used for eval data sets
225
226 - `"assistants"`
227
228 - `"batch"`
229
230 - `"fine-tune"`
231
232 - `"vision"`
233
234 - `"user_data"`
235
236 - `"evals"`
237
238- `expires_after: Optional[ExpiresAfter]`
239
240 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.
241
242 - `anchor: Literal["created_at"]`
243
244 Anchor timestamp after which the expiration policy applies. Supported anchors: `created_at`.
245
246 - `"created_at"`
247
248 - `seconds: int`
249
250 The number of seconds after the anchor time that the file will expire. Must be between 3600 (1 hour) and 2592000 (30 days).
251
252### Returns
253
254- `class FileObject: …`
255
256 The `File` object represents a document that has been uploaded to OpenAI.
257
258 - `id: str`
259
260 The file identifier, which can be referenced in the API endpoints.
261
262 - `bytes: int`
263
264 The size of the file, in bytes.
265
266 - `created_at: int`
267
268 The Unix timestamp (in seconds) for when the file was created.
269
270 - `filename: str`
271
272 The name of the file.
273
274 - `object: Literal["file"]`
275
276 The object type, which is always `file`.
277
278 - `"file"`
279
280 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`
281
282 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
283
284 - `"assistants"`
285
286 - `"assistants_output"`
287
288 - `"batch"`
289
290 - `"batch_output"`
291
292 - `"fine-tune"`
293
294 - `"fine-tune-results"`
295
296 - `"vision"`
297
298 - `"user_data"`
299
300 - `status: Literal["uploaded", "processed", "error"]`
301
302 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
303
304 - `"uploaded"`
305
306 - `"processed"`
307
308 - `"error"`
309
310 - `expires_at: Optional[int]`
311
312 The Unix timestamp (in seconds) for when the file will expire.
313
314 - `status_details: Optional[str]`
315
316 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
317
318### Example
319
320```python
321import os
322from openai import OpenAI
323
324client = OpenAI(
325 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
326)
327file_object = client.files.create(
328 file=b"Example data",
329 purpose="assistants",
330)
331print(file_object.id)
332```
333
334#### Response
335
336```json
337{
338 "id": "id",
339 "bytes": 0,
340 "created_at": 0,
341 "filename": "filename",
342 "object": "file",
343 "purpose": "assistants",
344 "status": "uploaded",
345 "expires_at": 0,
346 "status_details": "status_details"
347}
348```
349
350### Example
351
352```python
353from openai import OpenAI
354client = OpenAI()
355
356client.files.create(
357 file=open("mydata.jsonl", "rb"),
358 purpose="fine-tune",
359 expires_after={
360 "anchor": "created_at",
361 "seconds": 2592000
362 }
363)
364```
365
366#### Response
367
368```json
369{
370 "id": "file-abc123",
371 "object": "file",
372 "bytes": 120000,
373 "created_at": 1677610602,
374 "expires_at": 1677614202,
375 "filename": "mydata.jsonl",
376 "purpose": "fine-tune",
377}
378```
379
380## Delete file
381
382`files.delete(strfile_id) -> FileDeleted`
383
384**delete** `/files/{file_id}`
385
386Delete a file and remove it from all vector stores.
387
388### Parameters
389
390- `file_id: str`
391
392### Returns
393
394- `class FileDeleted: …`
395
396 - `id: str`
397
398 - `deleted: bool`
399
400 - `object: Literal["file"]`
401
402 - `"file"`
403
404### Example
405
406```python
407import os
408from openai import OpenAI
409
410client = OpenAI(
411 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
412)
413file_deleted = client.files.delete(
414 "file_id",
415)
416print(file_deleted.id)
417```
418
419#### Response
420
421```json
422{
423 "id": "id",
424 "deleted": true,
425 "object": "file"
426}
427```
428
429### Example
430
431```python
432from openai import OpenAI
433client = OpenAI()
434
435client.files.delete("file-abc123")
436```
437
438#### Response
439
440```json
441{
442 "id": "file-abc123",
443 "object": "file",
444 "deleted": true
445}
446```
447
448## Retrieve file
449
450`files.retrieve(strfile_id) -> FileObject`
451
452**get** `/files/{file_id}`
453
454Returns information about a specific file.
455
456### Parameters
457
458- `file_id: str`
459
460### Returns
461
462- `class FileObject: …`
463
464 The `File` object represents a document that has been uploaded to OpenAI.
465
466 - `id: str`
467
468 The file identifier, which can be referenced in the API endpoints.
469
470 - `bytes: int`
471
472 The size of the file, in bytes.
473
474 - `created_at: int`
475
476 The Unix timestamp (in seconds) for when the file was created.
477
478 - `filename: str`
479
480 The name of the file.
481
482 - `object: Literal["file"]`
483
484 The object type, which is always `file`.
485
486 - `"file"`
487
488 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`
489
490 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
491
492 - `"assistants"`
493
494 - `"assistants_output"`
495
496 - `"batch"`
497
498 - `"batch_output"`
499
500 - `"fine-tune"`
501
502 - `"fine-tune-results"`
503
504 - `"vision"`
505
506 - `"user_data"`
507
508 - `status: Literal["uploaded", "processed", "error"]`
509
510 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
511
512 - `"uploaded"`
513
514 - `"processed"`
515
516 - `"error"`
517
518 - `expires_at: Optional[int]`
519
520 The Unix timestamp (in seconds) for when the file will expire.
521
522 - `status_details: Optional[str]`
523
524 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
525
526### Example
527
528```python
529import os
530from openai import OpenAI
531
532client = OpenAI(
533 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
534)
535file_object = client.files.retrieve(
536 "file_id",
537)
538print(file_object.id)
539```
540
541#### Response
542
543```json
544{
545 "id": "id",
546 "bytes": 0,
547 "created_at": 0,
548 "filename": "filename",
549 "object": "file",
550 "purpose": "assistants",
551 "status": "uploaded",
552 "expires_at": 0,
553 "status_details": "status_details"
554}
555```
556
557### Example
558
559```python
560from openai import OpenAI
561client = OpenAI()
562
563client.files.retrieve("file-abc123")
564```
565
566#### Response
567
568```json
569{
570 "id": "file-abc123",
571 "object": "file",
572 "bytes": 120000,
573 "created_at": 1677610602,
574 "expires_at": 1677614202,
575 "filename": "mydata.jsonl",
576 "purpose": "fine-tune",
577}
578```
579
580## Retrieve file content
581
582`files.content(strfile_id) -> BinaryResponseContent`
583
584**get** `/files/{file_id}/content`
585
586Returns the contents of the specified file.
587
588### Parameters
589
590- `file_id: str`
591
592### Returns
593
594- `BinaryResponseContent`
595
596### Example
597
598```python
599import os
600from openai import OpenAI
601
602client = OpenAI(
603 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
604)
605response = client.files.content(
606 "file_id",
607)
608print(response)
609content = response.read()
610print(content)
611```
612
613### Example
614
615```python
616from openai import OpenAI
617client = OpenAI()
618
619content = client.files.content("file-abc123")
620```
621
622## Retrieve file content
623
624`files.retrieve_content(strfile_id) -> FileContent`
625
626**get** `/files/{file_id}/content`
627
628Returns the contents of the specified file.
629
630### Parameters
631
632- `file_id: str`
633
634### Returns
635
636- `str`
637
638### Example
639
640```python
641import os
642from openai import OpenAI
643
644client = OpenAI(
645 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
646)
647file_content = client.files.retrieve_content(
648 "file_id",
649)
650print(file_content)
651```
652
653#### Response
654
655```json
656"string"
657```
658
659### Example
660
661```python
662from openai import OpenAI
663client = OpenAI()
664
665content = client.files.content("file-abc123")
666```
667
668## Domain Types
669
670### File Content
671
672- `str`
673
674### File Deleted
675
676- `class FileDeleted: …`
677
678 - `id: str`
679
680 - `deleted: bool`
681
682 - `object: Literal["file"]`
683
684 - `"file"`
685
686### File Object
687
688- `class FileObject: …`
689
690 The `File` object represents a document that has been uploaded to OpenAI.
691
692 - `id: str`
693
694 The file identifier, which can be referenced in the API endpoints.
695
696 - `bytes: int`
697
698 The size of the file, in bytes.
699
700 - `created_at: int`
701
702 The Unix timestamp (in seconds) for when the file was created.
703
704 - `filename: str`
705
706 The name of the file.
707
708 - `object: Literal["file"]`
709
710 The object type, which is always `file`.
711
712 - `"file"`
713
714 - `purpose: Literal["assistants", "assistants_output", "batch", 5 more]`
715
716 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
717
718 - `"assistants"`
719
720 - `"assistants_output"`
721
722 - `"batch"`
723
724 - `"batch_output"`
725
726 - `"fine-tune"`
727
728 - `"fine-tune-results"`
729
730 - `"vision"`
731
732 - `"user_data"`
733
734 - `status: Literal["uploaded", "processed", "error"]`
735
736 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
737
738 - `"uploaded"`
739
740 - `"processed"`
741
742 - `"error"`
743
744 - `expires_at: Optional[int]`
745
746 The Unix timestamp (in seconds) for when the file will expire.
747
748 - `status_details: Optional[str]`
749
750 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
751
752### File Purpose
753
754- `Literal["assistants", "batch", "fine-tune", 3 more]`
755
756 The intended purpose of the uploaded file. One of:
757
758 - `assistants`: Used in the Assistants API
759 - `batch`: Used in the Batch API
760 - `fine-tune`: Used for fine-tuning
761 - `vision`: Images used for vision fine-tuning
762 - `user_data`: Flexible file type for any purpose
763 - `evals`: Used for eval data sets
764
765 - `"assistants"`
766
767 - `"batch"`
768
769 - `"fine-tune"`
770
771 - `"vision"`
772
773 - `"user_data"`
774
775 - `"evals"`