class RubyLLM::UploadedFile
An UploadedFile is the metadata record for a file stored with a provider through its Files API. Upload a file once with ::upload, then reuse its provider id or URI, for example as a chat attachment or in a batch.
file = RubyLLM.upload("batch.jsonl", purpose: "batch") file.id # => "file_..." file.filename # => "batch.jsonl" file.byte_size # => 1234
File ids are provider-owned. Persist provider alongside id and pass it back when finding or downloading the file later.
Attributes
The file size in bytes.
The Time the provider stored the file.
Whether the provider allows downloading the file’s content.
The Time the provider will delete the file, or nil if it does not expire.
The filename reported by the provider.
The provider-assigned file identifier, such as "file_...".
The raw provider response data for the file, as a Hash.
The MIME type of the stored file.
The slug of the provider that stores the file.
The purpose the file was uploaded for, such as "batch", when the provider tracks one.
The provider-reported processing status of the file.
The provider URI for the file, such as a Gemini Files API URI or a gs:// or s3:// location for storage-backed providers.
Public Class Methods
# File lib/ruby_llm/uploaded_file.rb, line 129 def self.download(id, provider: nil, context: nil) DownloadedFile.new(provider_for(provider, context).download_file(id)) end
Downloads the provider file id and returns a DownloadedFile. Also available as RubyLLM.download.
RubyLLM.download(file.id, provider: :openai).save("report.pdf")
Not every provider allows downloads; see downloadable. Cohere downloads original uploaded bytes when preserved; generated datasets return JSONL and require the optional avro gem.
# File lib/ruby_llm/uploaded_file.rb, line 117 def self.find(id, provider: nil, context: nil) provider_for(provider, context).find_file(id) end
Fetches metadata for an existing provider file by id and returns an UploadedFile. When provider: is omitted, the provider of the configured default model is used.
file = RubyLLM::UploadedFile.find("file_123")
# File lib/ruby_llm/uploaded_file.rb, line 104 def self.upload(file, provider: nil, context: nil, filename: nil, purpose: nil, expires_in: nil, uri: nil, content_type: nil, provider_options: {}) options = { filename:, purpose:, expires_in:, uri:, content_type: }.compact options[:provider_options] = provider_options unless provider_options.empty? provider_for(provider, context).upload_file(file, **options) end
Uploads file to the provider’s Files API and returns an UploadedFile. file may be a path, an IO object, or an Attachment. When provider: is omitted, the provider of the configured default model is used. Also available as RubyLLM.upload.
RubyLLM::UploadedFile.upload("document.pdf", provider: :anthropic) RubyLLM::UploadedFile.upload(io, provider: :openai, purpose: "batch", filename: "batch.jsonl")
OpenAI and Azure require purpose:. Cohere uses purpose: for its dataset type, such as "embed-input". Pass expires_in: as a number of seconds to have the provider delete the file automatically; OpenAI, xAI, and Mistral support it, and Mistral rounds up to whole hours. Storage-backed providers (Vertex AI and Bedrock) store the file at uri: when given, otherwise at a generated object name under the configured bucket. content_type: overrides the MIME type RubyLLM detects. provider_options: carries the rest in the provider’s own vocabulary: visibility: on Mistral, display_name: on Gemini.
Public Instance Methods
Source
# File lib/ruby_llm/uploaded_file.rb, line 81 def expired? !expires_at.nil? && expires_at <= Time.now + EXPIRY_MARGIN end
Returns true once the provider’s retention window for this file has passed or is about to; a file expiring within the next minute cannot safely serve a request. Files without a reported expiry never expire.