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 227 def self.download(id, provider: nil, context: nil) provider_for(provider, context).download_file(id) end
Downloads the content of the provider file id and returns the raw body. Also available as RubyLLM.download.
content = RubyLLM.download(file.id)
Not every provider allows downloads; see downloadable.
# File lib/ruby_llm/uploaded_file.rb, line 217 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 203 def self.upload(file, provider: nil, context: nil, filename: nil, purpose: nil, expires_in: nil, # rubocop:disable Metrics/ParameterLists visibility: nil, display_name: nil, uri: nil, content_type: nil) options = { filename:, purpose:, expires_in:, visibility:, display_name:, uri:, content_type: } .compact 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:. 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. The remaining keywords are provider-specific options: visibility: (Mistral), display_name: (Gemini), and uri: and content_type: (storage-backed providers such as Vertex AI and Bedrock).