@spec delete(String.t(), file_opts()) :: :ok | {:error, term()}

Delete a file.

Parameters

• name - File resource name (e.g., "files/abc123")
• opts - Options

Examples

:ok = Gemini.APIs.Files.delete("files/abc123")

@spec download(Gemini.Types.File.t() | String.t(), file_opts()) ::
  {:ok, binary()} | {:error, term()}

Download a generated file's content.

Only works for files with source: :generated (e.g., from video generation). Uploaded files cannot be downloaded - you already have the source.

Parameters

• file - File struct or file name
• opts - Options

Examples

{:ok, file} = Gemini.APIs.Files.get("files/generated-video-123")
{:ok, video_data} = Gemini.APIs.Files.download(file)
File.write!("output.mp4", video_data)

@spec get(String.t(), file_opts()) :: {:ok, Gemini.Types.File.t()} | {:error, term()}

Get file metadata by name.

Parameters

• name - File resource name (e.g., "files/abc123")
• opts - Options

Examples

{:ok, file} = Gemini.APIs.Files.get("files/abc123")
IO.puts("State: #{file.state}")
IO.puts("MIME type: #{file.mime_type}")

@spec list(list_opts()) ::
  {:ok, Gemini.Types.ListFilesResponse.t()} | {:error, term()}

List all uploaded files.

Parameters

• opts - List options

Options

• :page_size - Number of files per page (default: 100, max: 1000)
• :page_token - Token from previous response for pagination
• :auth - Authentication strategy

Examples

# List first page
{:ok, response} = Gemini.APIs.Files.list()
Enum.each(response.files, fn file ->
  IO.puts("#{file.name}: #{file.mime_type}")
end)

# Paginate through all files
{:ok, all_files} = Gemini.APIs.Files.list_all()

@spec list_all(list_opts()) :: {:ok, [Gemini.Types.File.t()]} | {:error, term()}

List all files across all pages.

Automatically handles pagination to retrieve all files.

Parameters

• opts - List options (:page_size can be set, default 100)

Examples

{:ok, all_files} = Gemini.APIs.Files.list_all()
IO.puts("Total files: #{length(all_files)}")

@spec upload(Path.t() | String.t(), upload_opts()) ::
  {:ok, Gemini.Types.File.t()} | {:error, term()}

Upload a file to be used with Gemini models.

Parameters

• file_path - Path to the file to upload (string or Path)
• opts - Upload options

Options

• :name - Custom file resource name (auto-generated if not provided)
• :display_name - Human-readable display name (max 512 characters)
• :mime_type - MIME type (auto-detected from extension if not provided)
• :on_progress - Callback function fn(uploaded_bytes, total_bytes) -> any() for progress updates
• :auth - Authentication strategy (must be :gemini)

Returns

• {:ok, File.t()} - Successfully uploaded file with metadata
• {:error, reason} - Upload failed

Examples

# Simple upload
{:ok, file} = Gemini.APIs.Files.upload("path/to/image.png")
IO.puts("Uploaded: #{file.uri}")

# With display name
{:ok, file} = Gemini.APIs.Files.upload("document.pdf",
  display_name: "Important Document"
)

# With progress tracking
{:ok, file} = Gemini.APIs.Files.upload("large_video.mp4",
  on_progress: fn uploaded, total ->
    IO.puts("Progress: #{div(uploaded * 100, total)}%")
  end
)

@spec upload_data(binary(), upload_opts()) ::
  {:ok, Gemini.Types.File.t()} | {:error, term()}

Upload a file from binary data.

Parameters

• data - Binary data to upload
• opts - Upload options (:mime_type is required)

Examples

image_data = File.read!("image.png")
{:ok, file} = Gemini.APIs.Files.upload_data(image_data,
  mime_type: "image/png",
  display_name: "My Image"
)

@spec wait_for_processing(
  String.t(),
  keyword()
) :: {:ok, Gemini.Types.File.t()} | {:error, term()}

Wait for a file to finish processing.

Polls the file status until it reaches :active or :failed state.

Parameters

• name - File resource name
• opts - Options

Options

• :poll_interval - Milliseconds between status checks (default: 2000)
• :timeout - Maximum wait time in milliseconds (default: 300000 = 5 min)
• :on_status - Callback for status updates fn(File.t()) -> any()

Examples

{:ok, file} = Gemini.APIs.Files.upload("video.mp4")

{:ok, ready_file} = Gemini.APIs.Files.wait_for_processing(file.name,
  poll_interval: 5000,
  on_status: fn f -> IO.puts("Status: #{f.state}") end
)