cli/resources/files/index.md +0 −547 deleted
File Deleted View Diff
1# Files
2
3## List files
4
5`$ openai files list`
6
7**get** `/files`
8
9Returns a list of files.
10
11### Parameters
12
13- `--after: optional string`
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 number`
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 "asc" or "desc"`
22
23 Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
24
25- `--purpose: optional string`
26
27 Only return files with the given purpose.
28
29### Returns
30
31- `ListFilesResponse: object { data, first_id, has_more, 2 more }`
32
33 - `data: array of FileObject`
34
35 - `id: string`
36
37 The file identifier, which can be referenced in the API endpoints.
38
39 - `bytes: number`
40
41 The size of the file, in bytes.
42
43 - `created_at: number`
44
45 The Unix timestamp (in seconds) for when the file was created.
46
47 - `filename: string`
48
49 The name of the file.
50
51 - `object: "file"`
52
53 The object type, which is always `file`.
54
55 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
56
57 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
58
59 - `"assistants"`
60
61 - `"assistants_output"`
62
63 - `"batch"`
64
65 - `"batch_output"`
66
67 - `"fine-tune"`
68
69 - `"fine-tune-results"`
70
71 - `"vision"`
72
73 - `"user_data"`
74
75 - `status: "uploaded" or "processed" or "error"`
76
77 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
78
79 - `"uploaded"`
80
81 - `"processed"`
82
83 - `"error"`
84
85 - `expires_at: optional number`
86
87 The Unix timestamp (in seconds) for when the file will expire.
88
89 - `status_details: optional string`
90
91 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
92
93 - `first_id: string`
94
95 - `has_more: boolean`
96
97 - `last_id: string`
98
99 - `object: string`
100
101### Example
102
103```cli
104openai files list \
105 --api-key 'My API Key'
106```
107
108#### Response
109
110```json
111{
112 "data": [
113 {
114 "id": "id",
115 "bytes": 0,
116 "created_at": 0,
117 "filename": "filename",
118 "object": "file",
119 "purpose": "assistants",
120 "status": "uploaded",
121 "expires_at": 0,
122 "status_details": "status_details"
123 }
124 ],
125 "first_id": "file-abc123",
126 "has_more": false,
127 "last_id": "file-abc456",
128 "object": "list"
129}
130```
131
132## Upload file
133
134`$ openai files create`
135
136**post** `/files`
137
138Upload a file that can be used across various endpoints. Individual files
139can be up to 512 MB, and each project can store up to 2.5 TB of files in
140total. There is no organization-wide storage limit. Uploads to this
141endpoint are rate-limited to 1,000 requests per minute per authenticated
142user.
143
144- The Assistants API supports files up to 2 million tokens and of specific
145 file types. See the [Assistants Tools guide](https://platform.openai.com/docs/assistants/tools) for
146 details.
147- The Fine-tuning API only supports `.jsonl` files. The input also has
148 certain required formats for fine-tuning
149 [chat](https://platform.openai.com/docs/api-reference/fine-tuning/chat-input) or
150 [completions](https://platform.openai.com/docs/api-reference/fine-tuning/completions-input) models.
151- The Batch API only supports `.jsonl` files up to 200 MB in size. The input
152 also has a specific required
153 [format](https://platform.openai.com/docs/api-reference/batch/request-input).
154- For Retrieval or `file_search` ingestion, upload files here first. If
155 you need to attach multiple uploaded files to the same vector store, use
156 [`/vector_stores/{vector_store_id}/file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
157 instead of attaching them one by one. Vector store attachment has separate
158 limits from file upload, including 2,000 attached files per minute per
159 organization.
160
161Please [contact us](https://help.openai.com/) if you need to increase these
162storage limits.
163
164### Parameters
165
166- `--file: string`
167
168 The File object (not file name) to be uploaded.
169
170- `--purpose: "assistants" or "batch" or "fine-tune" or 3 more`
171
172 The intended purpose of the uploaded file. One of:
173
174 - `assistants`: Used in the Assistants API
175 - `batch`: Used in the Batch API
176 - `fine-tune`: Used for fine-tuning
177 - `vision`: Images used for vision fine-tuning
178 - `user_data`: Flexible file type for any purpose
179 - `evals`: Used for eval data sets
180
181- `--expires-after: optional object { anchor, seconds }`
182
183 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.
184
185### Returns
186
187- `file_object: object { id, bytes, created_at, 6 more }`
188
189 The `File` object represents a document that has been uploaded to OpenAI.
190
191 - `id: string`
192
193 The file identifier, which can be referenced in the API endpoints.
194
195 - `bytes: number`
196
197 The size of the file, in bytes.
198
199 - `created_at: number`
200
201 The Unix timestamp (in seconds) for when the file was created.
202
203 - `filename: string`
204
205 The name of the file.
206
207 - `object: "file"`
208
209 The object type, which is always `file`.
210
211 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
212
213 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
214
215 - `"assistants"`
216
217 - `"assistants_output"`
218
219 - `"batch"`
220
221 - `"batch_output"`
222
223 - `"fine-tune"`
224
225 - `"fine-tune-results"`
226
227 - `"vision"`
228
229 - `"user_data"`
230
231 - `status: "uploaded" or "processed" or "error"`
232
233 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
234
235 - `"uploaded"`
236
237 - `"processed"`
238
239 - `"error"`
240
241 - `expires_at: optional number`
242
243 The Unix timestamp (in seconds) for when the file will expire.
244
245 - `status_details: optional string`
246
247 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
248
249### Example
250
251```cli
252openai files create \
253 --api-key 'My API Key' \
254 --file 'Example data' \
255 --purpose assistants
256```
257
258#### Response
259
260```json
261{
262 "id": "id",
263 "bytes": 0,
264 "created_at": 0,
265 "filename": "filename",
266 "object": "file",
267 "purpose": "assistants",
268 "status": "uploaded",
269 "expires_at": 0,
270 "status_details": "status_details"
271}
272```
273
274## Delete file
275
276`$ openai files delete`
277
278**delete** `/files/{file_id}`
279
280Delete a file and remove it from all vector stores.
281
282### Parameters
283
284- `--file-id: string`
285
286 The ID of the file to use for this request.
287
288### Returns
289
290- `file_deleted: object { id, deleted, object }`
291
292 - `id: string`
293
294 - `deleted: boolean`
295
296 - `object: "file"`
297
298### Example
299
300```cli
301openai files delete \
302 --api-key 'My API Key' \
303 --file-id file_id
304```
305
306#### Response
307
308```json
309{
310 "id": "id",
311 "deleted": true,
312 "object": "file"
313}
314```
315
316## Retrieve file
317
318`$ openai files retrieve`
319
320**get** `/files/{file_id}`
321
322Returns information about a specific file.
323
324### Parameters
325
326- `--file-id: string`
327
328 The ID of the file to use for this request.
329
330### Returns
331
332- `file_object: object { id, bytes, created_at, 6 more }`
333
334 The `File` object represents a document that has been uploaded to OpenAI.
335
336 - `id: string`
337
338 The file identifier, which can be referenced in the API endpoints.
339
340 - `bytes: number`
341
342 The size of the file, in bytes.
343
344 - `created_at: number`
345
346 The Unix timestamp (in seconds) for when the file was created.
347
348 - `filename: string`
349
350 The name of the file.
351
352 - `object: "file"`
353
354 The object type, which is always `file`.
355
356 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
357
358 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
359
360 - `"assistants"`
361
362 - `"assistants_output"`
363
364 - `"batch"`
365
366 - `"batch_output"`
367
368 - `"fine-tune"`
369
370 - `"fine-tune-results"`
371
372 - `"vision"`
373
374 - `"user_data"`
375
376 - `status: "uploaded" or "processed" or "error"`
377
378 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
379
380 - `"uploaded"`
381
382 - `"processed"`
383
384 - `"error"`
385
386 - `expires_at: optional number`
387
388 The Unix timestamp (in seconds) for when the file will expire.
389
390 - `status_details: optional string`
391
392 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
393
394### Example
395
396```cli
397openai files retrieve \
398 --api-key 'My API Key' \
399 --file-id file_id
400```
401
402#### Response
403
404```json
405{
406 "id": "id",
407 "bytes": 0,
408 "created_at": 0,
409 "filename": "filename",
410 "object": "file",
411 "purpose": "assistants",
412 "status": "uploaded",
413 "expires_at": 0,
414 "status_details": "status_details"
415}
416```
417
418## Retrieve file content
419
420`$ openai files content`
421
422**get** `/files/{file_id}/content`
423
424Returns the contents of the specified file.
425
426### Parameters
427
428- `--file-id: string`
429
430 The ID of the file to use for this request.
431
432### Returns
433
434- `unnamed_schema_0: file path`
435
436### Example
437
438```cli
439openai files content \
440 --api-key 'My API Key' \
441 --file-id file_id
442```
443
444## Domain Types
445
446### File Content
447
448- `file_content: string`
449
450### File Deleted
451
452- `file_deleted: object { id, deleted, object }`
453
454 - `id: string`
455
456 - `deleted: boolean`
457
458 - `object: "file"`
459
460### File Object
461
462- `file_object: object { id, bytes, created_at, 6 more }`
463
464 The `File` object represents a document that has been uploaded to OpenAI.
465
466 - `id: string`
467
468 The file identifier, which can be referenced in the API endpoints.
469
470 - `bytes: number`
471
472 The size of the file, in bytes.
473
474 - `created_at: number`
475
476 The Unix timestamp (in seconds) for when the file was created.
477
478 - `filename: string`
479
480 The name of the file.
481
482 - `object: "file"`
483
484 The object type, which is always `file`.
485
486 - `purpose: "assistants" or "assistants_output" or "batch" or 5 more`
487
488 The intended purpose of the file. Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, `fine-tune`, `fine-tune-results`, `vision`, and `user_data`.
489
490 - `"assistants"`
491
492 - `"assistants_output"`
493
494 - `"batch"`
495
496 - `"batch_output"`
497
498 - `"fine-tune"`
499
500 - `"fine-tune-results"`
501
502 - `"vision"`
503
504 - `"user_data"`
505
506 - `status: "uploaded" or "processed" or "error"`
507
508 Deprecated. The current status of the file, which can be either `uploaded`, `processed`, or `error`.
509
510 - `"uploaded"`
511
512 - `"processed"`
513
514 - `"error"`
515
516 - `expires_at: optional number`
517
518 The Unix timestamp (in seconds) for when the file will expire.
519
520 - `status_details: optional string`
521
522 Deprecated. For details on why a fine-tuning training file failed validation, see the `error` field on `fine_tuning.job`.
523
524### File Purpose
525
526- `file_purpose: "assistants" or "batch" or "fine-tune" or 3 more`
527
528 The intended purpose of the uploaded file. One of:
529
530 - `assistants`: Used in the Assistants API
531 - `batch`: Used in the Batch API
532 - `fine-tune`: Used for fine-tuning
533 - `vision`: Images used for vision fine-tuning
534 - `user_data`: Flexible file type for any purpose
535 - `evals`: Used for eval data sets
536
537 - `"assistants"`
538
539 - `"batch"`
540
541 - `"fine-tune"`
542
543 - `"vision"`
544
545 - `"user_data"`
546
547 - `"evals"`