Gemini.Types.File (GeminiEx v0.8.2)

View Source

Type definitions for file management operations.

The Files API allows uploading, downloading, and managing files that can be used with Gemini models for multimodal content generation.

File States

Files go through several states during processing:

  • :state_unspecified - Initial/unknown state
  • :processing - File is being processed
  • :active - File is ready to use
  • :failed - Processing failed

File Sources

  • :source_unspecified - Unknown source
  • :uploaded - User uploaded the file
  • :generated - API generated the file (e.g., from video generation)

Example

# Upload a file
{:ok, file} = Gemini.upload_file("path/to/image.png")

# Check file state
case file.state do
  :active -> IO.puts("File is ready: #{file.uri}")
  :processing -> IO.puts("Still processing...")
  :failed -> IO.puts("Failed: #{file.error}")
end

# Use in content generation
{:ok, response} = Gemini.generate([
  %{type: "text", text: "What's in this image?"},
  %{type: "file", uri: file.uri, mime_type: file.mime_type}
])

Summary

Types

file_source()

File source enumeration values.

file_state()

File state enumeration values.

file_status()

File status/error information.

t()

Represents a file in the Gemini API.

video_metadata()

Video metadata for video files.

Functions

active?(arg1)

Checks if the file is ready to use.

downloadable?(arg1)

Checks if the file can be downloaded (only generated files).

failed?(arg1)

Checks if the file processing failed.

from_api_response(response)

Creates a new File struct from API response.

get_id(file)

Extracts the file ID from the file name.

parse_source(arg1)

Parses API source string to atom.

parse_state(arg1)

Parses API state string to atom.

processing?(arg1)

Checks if the file is still processing.

source_to_api(atom)

Converts file source atom to API string format.

state_to_api(atom)

Converts file state atom to API string format.

Types

file_source()

@type file_source() :: :source_unspecified | :uploaded | :generated

File source enumeration values.

  • :source_unspecified - Unknown source
  • :uploaded - User uploaded the file
  • :generated - API generated the file (e.g., video generation)

file_state()

@type file_state() :: :state_unspecified | :processing | :active | :failed

File state enumeration values.

  • :state_unspecified - Initial/unknown state
  • :processing - File is being processed by the API
  • :active - File is ready to use in requests
  • :failed - File processing failed (check error field)

file_status()

@type file_status() :: %{
  optional(:message) => String.t(),
  optional(:code) => integer()
}

File status/error information.

t()

@type t() :: %Gemini.Types.File{
  create_time: String.t() | nil,
  display_name: String.t() | nil,
  download_uri: String.t() | nil,
  error: file_status() | nil,
  expiration_time: String.t() | nil,
  mime_type: String.t() | nil,
  name: String.t() | nil,
  sha256_hash: String.t() | nil,
  size_bytes: integer() | nil,
  source: file_source() | nil,
  state: file_state() | nil,
  update_time: String.t() | nil,
  uri: String.t() | nil,
  video_metadata: video_metadata() | nil
}

Represents a file in the Gemini API.

Writable Fields (can be set on upload)

  • name - Resource name (format: "files/{file_id}")
  • display_name - Human-readable display name (max 512 characters)
  • mime_type - MIME type (e.g., "image/png", "video/mp4")

Read-Only Fields (output only)

  • size_bytes - File size in bytes
  • create_time - Creation timestamp (ISO 8601)
  • expiration_time - When the file expires (ISO 8601)
  • update_time - Last update timestamp (ISO 8601)
  • sha256_hash - Base64-encoded SHA256 hash
  • uri - URI for using the file in content (e.g., "gs://...")
  • download_uri - Download URI (only for generated files)
  • state - Current processing state
  • source - How the file was created
  • video_metadata - Metadata for video files
  • error - Error information if state is :failed

video_metadata()

@type video_metadata() :: %{
  optional(:video_duration) => String.t(),
  optional(:video_duration_seconds) => integer()
}

Video metadata for video files.

Functions

active?(arg1)

@spec active?(t()) :: boolean()

Checks if the file is ready to use.

downloadable?(arg1)

@spec downloadable?(t()) :: boolean()

Checks if the file can be downloaded (only generated files).

failed?(arg1)

@spec failed?(t()) :: boolean()

Checks if the file processing failed.

from_api_response(response)

@spec from_api_response(map()) :: t()

Creates a new File struct from API response.

Parameters

  • response - Map from API response with string keys

Examples

response = %{
  "name" => "files/abc123",
  "displayName" => "my-image.png",
  "mimeType" => "image/png",
  "sizeBytes" => "1024",
  "state" => "ACTIVE"
}
file = Gemini.Types.File.from_api_response(response)

get_id(file)

@spec get_id(t()) :: String.t() | nil

Extracts the file ID from the file name.

Examples

file = %Gemini.Types.File{name: "files/abc123"}
Gemini.Types.File.get_id(file)
# => "abc123"

parse_source(arg1)

@spec parse_source(String.t() | nil) :: file_source() | nil

Parses API source string to atom.

parse_state(arg1)

@spec parse_state(String.t() | nil) :: file_state() | nil

Parses API state string to atom.

processing?(arg1)

@spec processing?(t()) :: boolean()

Checks if the file is still processing.

source_to_api(atom)

@spec source_to_api(file_source()) :: String.t()

Converts file source atom to API string format.

state_to_api(atom)

@spec state_to_api(file_state()) :: String.t()

Converts file state atom to API string format.