# `Gemini.Types.File`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L1)

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)
- `:registered` - File registered from GCS via RegisterFiles API

## Example

    # Upload a file
    {:ok, file} = Gemini.APIs.Files.upload("path/to/image.png", auth: :gemini)

    # 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 the File struct directly in content generation
    {:ok, response} = Gemini.generate([file, "What's in this image?"])

# `file_source`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L64)

```elixir
@type file_source() :: :source_unspecified | :uploaded | :generated | :registered
```

File source enumeration values.

- `:source_unspecified` - Unknown source
- `:uploaded` - User uploaded the file
- `:generated` - API generated the file (e.g., video generation)
- `:registered` - File registered from GCS via RegisterFiles API

# `file_state`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L50)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L81)

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

File status/error information.

# `t`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L87)

```elixir
@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 (for example a Gemini Files URI)
- `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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L73)

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

Video metadata for video files.

# `active?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L216)

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

Checks if the file is ready to use.

# `downloadable?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L237)

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

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

# `failed?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L230)

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

Checks if the file processing failed.

# `from_api_response`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L150)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L253)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L205)

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

Parses API source string to atom.

# `parse_state`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L185)

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

Parses API state string to atom.

# `processing?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L223)

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

Checks if the file is still processing.

# `source_to_api`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L196)

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

Converts file source atom to API string format.

# `state_to_api`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/types/file.ex#L176)

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

Converts file state atom to API string format.

---

*Consult [api-reference.md](api-reference.md) for complete listing*