ReqLLM.Providers.OpenAI.Files (ReqLLM v1.19.0)

OpenAI-scoped lifecycle operations for reusable provider files.

Uploaded and retrieved files are returned as explicitly owned ReqLLM.Message.ContentPart values. They can be passed directly to an OpenAI Responses request without changing ReqLLM's common provider behaviour or legacy ContentPart.file_id/1 contract.

Upload and reuse

alias ReqLLM.Message.ContentPart
alias ReqLLM.Providers.OpenAI.Files

{:ok, file} =
  Files.upload(
    ContentPart.file(pdf_bytes, "report.pdf", "application/pdf"),
    purpose: :user_data
  )

context =
  ReqLLM.Context.new([
    ReqLLM.Context.user([
      ContentPart.text("Summarize this report."),
      file
    ])
  ])

{:ok, response} = ReqLLM.generate_text("openai:gpt-5", context)
{:ok, true} = Files.delete(file)

upload/2 also accepts a local path or an explicit {:binary, data, filename, media_type} tuple. The default purpose is :user_data.

OpenAI retains most files until they are deleted. Pass :expires_after as a number of seconds from creation when automatic expiry is appropriate, or call delete/2 when the file is no longer needed.

Summary

Types

source()

Functions

delete(file, opts \\ [])

Deletes an OpenAI file.

delete!(file, opts \\ [])

Same as delete/2, but raises on error.

list(opts \\ [])

Lists OpenAI files as canonical owned references.

list!(opts \\ [])

Same as list/1, but raises on error.

retrieve(file, opts \\ [])

Retrieves current metadata for an OpenAI file.

retrieve!(file, opts \\ [])

Same as retrieve/2, but raises on error.

upload(source, opts \\ [])

Uploads a file to OpenAI and returns its owned provider reference.

upload!(source, opts \\ [])

Same as upload/2, but raises on error.

Types

source()

@type source() ::
  String.t()
  | ReqLLM.Message.ContentPart.t()
  | {:binary, binary(), String.t()}
  | {:binary, binary(), String.t(), String.t()}

Functions

delete(file, opts \\ [])

@spec delete(
  String.t() | ReqLLM.Message.ContentPart.t(),
  keyword()
) :: {:ok, boolean()} | {:error, Exception.t()}

Deletes an OpenAI file.

Returns {:ok, true} when OpenAI confirms deletion. Explicitly owned references are checked for OpenAI ownership before any HTTP request.

delete!(file, opts \\ [])

@spec delete!(
  String.t() | ReqLLM.Message.ContentPart.t(),
  keyword()
) :: boolean() | no_return()

Same as delete/2, but raises on error.

list(opts \\ [])

@spec list(keyword()) ::
  {:ok, ReqLLM.Providers.OpenAI.Files.Page.t()} | {:error, Exception.t()}

Lists OpenAI files as canonical owned references.

Supports the OpenAI query options :after, :limit, :order, and :purpose, alongside the shared request and authentication options accepted by upload/2. :after accepts either a file ID or a returned file reference.

list!(opts \\ [])

@spec list!(keyword()) :: ReqLLM.Providers.OpenAI.Files.Page.t() | no_return()

Same as list/1, but raises on error.

retrieve(file, opts \\ [])

@spec retrieve(
  String.t() | ReqLLM.Message.ContentPart.t(),
  keyword()
) :: {:ok, ReqLLM.Message.ContentPart.t()} | {:error, Exception.t()}

Retrieves current metadata for an OpenAI file.

Accepts either a file ID or a ContentPart. Explicitly owned references are checked for OpenAI ownership and known expiry before any HTTP request.

retrieve!(file, opts \\ [])

@spec retrieve!(
  String.t() | ReqLLM.Message.ContentPart.t(),
  keyword()
) :: ReqLLM.Message.ContentPart.t() | no_return()

Same as retrieve/2, but raises on error.

upload(source, opts \\ [])

@spec upload(
  source(),
  keyword()
) :: {:ok, ReqLLM.Message.ContentPart.t()} | {:error, Exception.t()}

Uploads a file to OpenAI and returns its owned provider reference.

Sources may be a local path, an inline file ContentPart, {:binary, data, filename}, or {:binary, data, filename, media_type}.

Options

:purpose - OpenAI file purpose; defaults to :user_data
:expires_after - seconds after creation, from 3,600 through 2,592,000
:media_type - override the inferred media type
:base_url - override the OpenAI API base URL
:api_key, :auth_mode, :access_token, :provider_options - normal OpenAI authentication options
:receive_timeout, :total_timeout, :max_retries - request controls
:req_http_options - options merged into the Req request
:telemetry - ReqLLM telemetry options
:fixture - ReqLLM fixture name for tests

upload!(source, opts \\ [])

@spec upload!(
  source(),
  keyword()
) :: ReqLLM.Message.ContentPart.t() | no_return()

Same as upload/2, but raises on error.