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