Class: OpenAI::Resources::Files

Inherits:
Object
  • Object
show all
Defined in:
lib/openai/resources/files.rb,
sig/openai/resources/files.rbs

Overview

Files are used to upload documents that can be used with features like Assistants and Fine-tuning.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Files

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Files.

Parameters:



230
231
232
 
# File 'lib/openai/resources/files.rb', line 230

def initialize(client:)
  @client = client
end

Instance Method Details

#content(file_id, request_options: {}) ⇒ StringIO

Returns a response containing the contents of the specified file.

Parameters:

  • file_id (String) —

    The ID of the file to use for this request.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (StringIO)

See Also:



179
180
181
182
183
184
185
186
187
188
 
# File 'lib/openai/resources/files.rb', line 179

def content(file_id, params = {})
  @client.request(
    method: :get,
    path: ["files/%1$s/content", file_id],
    headers: {"accept" => "application/binary"},
    model: StringIO,
    security: {bearer_auth: true},
    options: params[:request_options]
  )
end

#create(file:, purpose:, expires_after: nil, request_options: {}) ⇒ OpenAI::Models::FileObject

Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and each project can store up to 2.5 TB of files in total. There is no organization-wide storage limit. Uploads to this endpoint are rate-limited to 1,000 requests per minute per authenticated user.

  • The Assistants API supports files up to 2 million tokens and of specific file types. See the Assistants Tools guide for details.
  • The Fine-tuning API only supports .jsonl files. The input also has certain required formats for fine-tuning chat or completions models.
  • The Batch API only supports .jsonl files up to 200 MB in size. The input also has a specific required format.
  • For Retrieval or file_search ingestion, upload files here first. If you need to attach multiple uploaded files to the same vector store, use /vector_stores/{vector_store_id}/file_batches instead of attaching them one by one. Vector store attachment has separate limits from file upload, including 2,000 attached files per minute per organization.

Please contact us if you need to increase these storage limits.

String, StringIO, and pathless IO inputs are sent with generic upload metadata. Use OpenAI::FilePart when you need to override the filename or content type.

Parameters:

  • file (Pathname, StringIO, IO, String, OpenAI::FilePart) —

    The File object (not file name) to be uploaded.

    String, StringIO, and pathless IO inputs are sent with generic upload metadata. Use OpenAI::FilePart when you need to override the filename or content type.

  • purpose (Symbol, OpenAI::Models::FilePurpose) —

    The intended purpose of the uploaded file. One of:

    • assistants: Used in the Assistants API
    • batch: Used in the Batch API
    • fine-tune: Used for fine-tuning
    • vision: Images used for vision fine-tuning
    • user_data: Flexible file type for any purpose
    • evals: Used for eval data sets
  • expires_after (OpenAI::Models::FileCreateParams::ExpiresAfter) —

    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.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/openai/resources/files.rb', line 70

def create(params)
  parsed, options = OpenAI::FileCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "files",
    headers: {"content-type" => "multipart/form-data"},
    body: parsed,
    model: OpenAI::FileObject,
    security: {bearer_auth: true},
    options: options
  )
end

#delete(file_id, request_options: {}) ⇒ OpenAI::Models::FileDeleted

Delete a file and remove it from all vector stores.

Parameters:

  • file_id (String) —

    The ID of the file to use for this request.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



157
158
159
160
161
162
163
164
165
 
# File 'lib/openai/resources/files.rb', line 157

def delete(file_id, params = {})
  @client.request(
    method: :delete,
    path: ["files/%1$s", file_id],
    model: OpenAI::FileDeleted,
    security: {bearer_auth: true},
    options: params[:request_options]
  )
end

#list(after: nil, limit: nil, order: nil, purpose: nil, request_options: {}) ⇒ OpenAI::Internal::CursorPage<OpenAI::Models::FileObject>

Returns a list of files.

Parameters:

  • after (String) —

    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.

  • limit (Integer) —

    A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.

  • order (Symbol, OpenAI::Models::FileListParams::Order) —

    Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

  • purpose (String) —

    Only return files with the given purpose.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/openai/resources/files.rb', line 131

def list(params = {})
  parsed, options = OpenAI::FileListParams.dump_request(params)
  query = OpenAI::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "files",
    query: query,
    page: OpenAI::Internal::CursorPage,
    model: OpenAI::FileObject,
    security: {bearer_auth: true},
    options: options
  )
end

#retrieve(file_id, request_options: {}) ⇒ OpenAI::Models::FileObject

Returns information about a specific file.

Parameters:

  • file_id (String) —

    The ID of the file to use for this request.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



95
96
97
98
99
100
101
102
103
 
# File 'lib/openai/resources/files.rb', line 95

def retrieve(file_id, params = {})
  @client.request(
    method: :get,
    path: ["files/%1$s", file_id],
    model: OpenAI::FileObject,
    security: {bearer_auth: true},
    options: params[:request_options]
  )
end

#wait_for_processing(file_id, poll_interval: nil, timeout: 1800.0, request_options: {}) ⇒ OpenAI::Models::FileObject

Wait for an uploaded file to finish processing.

The returned file may have an error status; callers should inspect the status before using it. Polling intervals and the overall timeout are in seconds. Finite timeouts include authentication and request replay time and disable transport retries so the deadline remains strict. Set timeout to nil to wait indefinitely and retain configured transport retries.

Parameters:

  • file_id (String) —

    The ID of the file to wait for.

  • poll_interval (Integer, Float, nil) (defaults to: nil) —

    How often to retrieve the file. When omitted, the SDK honors the server's polling hint and otherwise waits 5 seconds.

  • timeout (Integer, Float, nil) (defaults to: OpenAI::Internal::Poller::DEFAULT_TIMEOUT) —

    Maximum total time to poll. Defaults to 30 minutes. Set to nil to wait indefinitely.

  • request_options (OpenAI::RequestOptions, Hash{Symbol=>Object}, nil) (defaults to: {})

Returns:

Raises:



212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/openai/resources/files.rb', line 212

def wait_for_processing(
  file_id,
  poll_interval: nil,
  timeout: OpenAI::Internal::Poller::DEFAULT_TIMEOUT,
  request_options: {}
)
  OpenAI::Helpers::ResourcePolling.wait_for_file(
    self,
    file_id,
    poll_interval: poll_interval,
    timeout: timeout,
    request_options: request_options
  )
end