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