# `Gemini.APIs.Models`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L1)

Complete Models API implementation following the unified architecture.

Provides comprehensive access to Gemini model information including:
- Listing available models with pagination
- Getting detailed model information
- Querying model capabilities and features
- Statistical analysis and filtering

## Examples

    # List all available models
    {:ok, response} = Models.list()
    models = response.models

    # Get specific model information
    {:ok, model} = Models.get("gemini-3.1-pro-preview")

    # Check if model exists
    {:ok, true} = Models.exists?("gemini-flash-lite-latest")

    # Filter models by capabilities
    {:ok, streaming_models} = Models.supporting_method("streamGenerateContent")

# `exists?`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L216)

```elixir
@spec exists?(String.t()) :: {:ok, boolean()} | {:error, Gemini.Error.t()}
```

Check if a specific model exists and is available.

## Parameters
- `model_name` - The model identifier to check

## Returns
- `{:ok, true}` - Model exists and is available
- `{:ok, false}` - Model does not exist
- `{:error, Error.t()}` - Network or other API error

## Examples

    {:ok, true} = Models.exists?("gemini-flash-lite-latest")
    {:ok, false} = Models.exists?("nonexistent-model")

    # Use in conditional logic
    case Models.exists?("gemini-flash-lite-latest") do
      {:ok, true} -> generate_with_model("gemini-flash-lite-latest")
      {:ok, false} -> use_fallback_model()
      {:error, _} -> handle_api_error()
    end

# `filter`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L313)

```elixir
@spec filter(keyword()) ::
  {:ok, [Gemini.Types.Response.Model.t()]} | {:error, Gemini.Error.t()}
```

Get models filtered by capabilities or parameters.

## Parameters
- `filter_opts` - Keyword list of filter criteria:
  - `:min_input_tokens` - Minimum input token limit
  - `:min_output_tokens` - Minimum output token limit
  - `:supports_methods` - List of required methods
  - `:has_temperature` - Boolean, requires temperature parameter
  - `:has_top_k` - Boolean, requires top_k parameter
  - `:has_top_p` - Boolean, requires top_p parameter
  - `:production_ready` - Boolean, filter for production-ready models
  - `:model_family` - String, filter by model family (e.g., "gemini")

## Returns
- `{:ok, [Model.t()]}` - Filtered list of models
- `{:error, Error.t()}` - API error

## Examples

    # High-capacity models
    {:ok, large_models} = Models.filter(min_input_tokens: 100_000)

    # Models with advanced parameters
    {:ok, tunable_models} = Models.filter(has_temperature: true, has_top_k: true)

    # Multi-method support
    {:ok, versatile_models} = Models.filter(
      supports_methods: ["generateContent", "streamGenerateContent"]
    )

    # Production-ready models only
    {:ok, production_models} = Models.filter(production_ready: true)

# `get`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L118)

```elixir
@spec get(String.t()) ::
  {:ok, Gemini.Types.Response.Model.t()} | {:error, Gemini.Error.t()}
```

Get detailed information about a specific model.

## Parameters
- `model_name` - The model identifier, with or without "models/" prefix
  Examples: "gemini-flash-lite-latest", "models/gemini-3-pro-preview"

## Returns
- `{:ok, Model.t()}` - Success with model details
- `{:error, Error.t()}` - Model not found, validation error, or API error

## Examples

    # Get model by base ID
    {:ok, model} = Models.get("gemini-flash-lite-latest")

    # Get model by full resource name
    {:ok, model} = Models.get("models/gemini-2.5-pro")

    # Handle not found cases properly in your application code

## API Reference
Corresponds to: `GET https://generativelanguage.googleapis.com/v1beta/{name=models/*}`

# `get_stats`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L362)

```elixir
@spec get_stats() :: {:ok, map()} | {:error, Gemini.Error.t()}
```

Get comprehensive model statistics and summary.

## Returns
- `{:ok, map()}` - Statistics about available models
- `{:error, Error.t()}` - API error

## Example Response

    {:ok, stats} = Models.get_stats()
    # =>
    # %{
    #   total_models: 5,
    #   by_version: %{"1.5" => 3, "2.0" => 2},
    #   by_method: %{
    #     "generateContent" => 5,
    #     "streamGenerateContent" => 4,
    #     "countTokens" => 5
    #   },
    #   token_limits: %{
    #     max_input: 2_000_000,
    #     max_output: 8192,
    #     avg_input: 800_000,
    #     avg_output: 4096
    #   },
    #   capabilities: %{
    #     with_temperature: 5,
    #     with_top_k: 3,
    #     with_top_p: 5,
    #     production_ready: 4
    #   },
    #   by_family: %{"gemini" => 4, "text" => 1}
    # }

# `list`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L65)

```elixir
@spec list(keyword()) ::
  {:ok, Gemini.Types.Response.ListModelsResponse.t()}
  | {:error, Gemini.Error.t()}
```

List available Gemini models with optional pagination.

## Parameters
- `opts` - Keyword list of options:
  - `:page_size` - Maximum number of models per page (1-1000, default: 50)
  - `:page_token` - Token for retrieving the next page of results

## Returns
- `{:ok, ListModelsResponse.t()}` - Success with models and pagination info
- `{:error, Error.t()}` - Validation error, API error, or network failure

## Examples

    # List first 50 models (default)
    {:ok, response} = Models.list()
    models = response.models
    next_token = response.next_page_token

    # Custom page size
    {:ok, response} = Models.list(page_size: 10)

    # Pagination
    {:ok, page1} = Models.list(page_size: 10)
    {:ok, page2} = Models.list(page_size: 10, page_token: page1.next_page_token)

## API Reference
Corresponds to: `GET https://generativelanguage.googleapis.com/v1beta/models`

# `list_names`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L176)

```elixir
@spec list_names() :: {:ok, [String.t()]} | {:error, Gemini.Error.t()}
```

List all available model names as simple strings.

This is a convenience function that extracts just the base model IDs
from the full models list response.

## Returns
- `{:ok, [String.t()]}` - List of base model IDs
- `{:error, Error.t()}` - API error

## Examples

    {:ok, names} = Models.list_names()
    # => ["gemini-flash-lite-latest", "gemini-2.5-pro", "gemini-2.5-flash"]

    # Use with enum functions
    {:ok, names} = Models.list_names()
    flash_models = Enum.filter(names, &String.contains?(&1, "flash"))

# `supporting_method`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/enhanced_models.ex#L256)

```elixir
@spec supporting_method(String.t()) ::
  {:ok, [Gemini.Types.Response.Model.t()]} | {:error, Gemini.Error.t()}
```

Get models that support a specific generation method.

## Parameters
- `method` - The generation method to filter by
  Examples: "generateContent", "streamGenerateContent", "countTokens"

## Returns
- `{:ok, [Model.t()]}` - List of models supporting the method
- `{:error, Error.t()}` - API error

## Examples

    # Find streaming-capable models
    {:ok, streaming_models} = Models.supporting_method("streamGenerateContent")

    # Find models that support content generation
    {:ok, generation_models} = Models.supporting_method("generateContent")

    # Check capabilities
    {:ok, models} = Models.supporting_method("countTokens")
    token_counting_available = length(models) > 0

---

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