Gemini.Types.GenerationConfig (GeminiEx v0.8.2)

@type t() :: %Gemini.Types.GenerationConfig{
  candidate_count: integer() | nil,
  frequency_penalty: float() | nil,
  image_config: Gemini.Types.GenerationConfig.ImageConfig.t() | nil,
  logprobs: integer() | nil,
  max_output_tokens: integer() | nil,
  media_resolution: Gemini.Types.MediaResolution.t() | nil,
  presence_penalty: float() | nil,
  property_ordering: [String.t()] | nil,
  response_logprobs: boolean() | nil,
  response_mime_type: String.t() | nil,
  response_modalities: [Gemini.Types.Modality.t()] | nil,
  response_schema: map() | nil,
  seed: integer() | nil,
  speech_config: Gemini.Types.SpeechConfig.t() | nil,
  stop_sequences: [String.t()],
  temperature: float() | nil,
  thinking_config: Gemini.Types.GenerationConfig.ThinkingConfig.t() | nil,
  top_k: integer() | nil,
  top_p: float() | nil
}

Functions

balanced(opts \\ [])

Create a balanced generation config.

creative(opts \\ [])

Create a creative generation config (higher temperature).

deterministic(opts \\ [])

Create a deterministic generation config.

image_config(config \\ %MODULE{}, opts)

@spec image_config(
  t(),
  keyword()
) :: t()

Configure image generation settings for Gemini 3 Pro Image.

Used with gemini-3-pro-image-preview model for generating images.

Parameters

config: GenerationConfig struct (defaults to new config)
opts: Keyword list of image options
- :aspect_ratio - Output aspect ratio (e.g., "16:9", "1:1", "4:3", "3:4", "9:16")
- :image_size - Output resolution ("2K" or "4K")

Examples

# Generate 4K landscape image
config = GenerationConfig.image_config(aspect_ratio: "16:9", image_size: "4K")

# Generate square image at 2K
config = GenerationConfig.image_config(aspect_ratio: "1:1", image_size: "2K")

# Chain with other options
config =
  GenerationConfig.new()
  |> GenerationConfig.image_config(aspect_ratio: "16:9", image_size: "4K")

include_thoughts(config \\ %MODULE{}, include)

@spec include_thoughts(t(), boolean()) :: t()

Enable thought summaries in model response.

When enabled, the model includes a summary of its reasoning process.

Parameters

config: GenerationConfig struct (defaults to new config)
include: Boolean to enable/disable thought summaries

Examples

# Enable thought summaries
config = GenerationConfig.include_thoughts(true)

# Combine with thinking budget
config =
  GenerationConfig.new()
  |> GenerationConfig.thinking_budget(2048)
  |> GenerationConfig.include_thoughts(true)

json_response(config \\ %MODULE{})

Set JSON response format.

max_tokens(config \\ %MODULE{}, tokens)

Set maximum output tokens.

media_resolution(config \\ %MODULE{}, resolution)

@spec media_resolution(t(), Gemini.Types.MediaResolution.t()) :: t()

Set media resolution preference.

new(opts \\ [])

Create a new generation config with default values.

precise(opts \\ [])

Create a precise generation config (lower temperature).

property_ordering(config \\ %MODULE{}, ordering)

@spec property_ordering(t(), [String.t()]) :: t()

Set property ordering for Gemini 2.0 models.

Explicitly defines the order in which properties appear in the generated JSON. Required for Gemini 2.0 Flash and Gemini 2.0 Flash-Lite when using structured outputs. Not needed for Gemini 2.5+ models (they preserve schema key order automatically).

Parameters

config: GenerationConfig struct (defaults to new config)
ordering: List of property names in desired order

Examples

# For Gemini 2.0 models
config = GenerationConfig.property_ordering(["name", "age", "email"])

# Chain with other options
config =
  GenerationConfig.new()
  |> GenerationConfig.json_response()
  |> GenerationConfig.property_ordering(["firstName", "lastName"])

Model Compatibility

Gemini 2.5+: Optional (implicit ordering from schema keys)
Gemini 2.0: Required when using structured outputs

response_modalities(config \\ %MODULE{}, modalities)

@spec response_modalities(t(), [Gemini.Types.Modality.t()]) :: t()

Set response modalities for the model output.

seed(config \\ %MODULE{}, value)

@spec seed(t(), integer()) :: t()

Set deterministic generation seed.

speech_config(config \\ %MODULE{}, speech_config)

@spec speech_config(t(), Gemini.Types.SpeechConfig.t()) :: t()

Set speech generation configuration.

stop_sequences(config \\ %MODULE{}, sequences)

Add stop sequences.

structured_json(config \\ %MODULE{}, schema)

@spec structured_json(t(), map()) :: t()

Configure structured JSON output with schema.

Convenience helper that sets both response MIME type and schema in one call. This is the recommended way to set up structured outputs.

Parameters

config: GenerationConfig struct (defaults to new config)
schema: JSON Schema map defining the output structure

Examples

# Basic structured output
config = GenerationConfig.structured_json(%{
  "type" => "object",
  "properties" => %{
    "answer" => %{"type" => "string"},
    "confidence" => %{"type" => "number"}
  }
})

# With property ordering for Gemini 2.0
config =
  GenerationConfig.structured_json(%{
    "type" => "object",
    "properties" => %{
      "name" => %{"type" => "string"},
      "age" => %{"type" => "integer"}
    }
  })
  |> GenerationConfig.property_ordering(["name", "age"])

# Complex schema with new keywords
config = GenerationConfig.structured_json(%{
  "type" => "object",
  "properties" => %{
    "score" => %{
      "type" => "number",
      "minimum" => 0,
      "maximum" => 100
    }
  }
})

Supported JSON Schema Keywords

Basic types: string, number, integer, boolean, object, array
Object: properties, required, additionalProperties
Array: items, prefixItems, minItems, maxItems
String: enum, format, pattern
Number: minimum, maximum, enum
Union types: anyOf
References: $ref
Nullable: type: ["string", "null"]

See docs/guides/structured_outputs.md for comprehensive examples.

temperature(config \\ %MODULE{}, temp)

@spec temperature(t(), float()) :: t()

Set temperature for response generation.

Controls randomness in the output. Higher values (e.g., 0.9) make output more random, while lower values (e.g., 0.1) make it more focused and deterministic.

Parameters

config: GenerationConfig struct (defaults to new config)
temp: Temperature value (typically 0.0 to 1.0)

Examples

# Low temperature for focused output
config = GenerationConfig.temperature(0.2)

# High temperature for creative output
config = GenerationConfig.temperature(0.9)

# Chain with other options
config =
  GenerationConfig.new()
  |> GenerationConfig.temperature(0.7)
  |> GenerationConfig.max_tokens(1000)

text_response(config \\ %MODULE{})

Set plain text response format.

thinking_budget(config \\ %MODULE{}, budget)

@spec thinking_budget(t(), integer()) :: t()

Set thinking budget for Gemini 2.5 series models (legacy).

For Gemini 3 models, use thinking_level/2 instead.

Controls how many thinking tokens the model can use for internal reasoning.

Parameters

config: GenerationConfig struct (defaults to new config)
budget: Integer controlling thinking tokens
- 0: Disable thinking (Flash/Lite only, NOT Pro)
- -1: Dynamic thinking (model decides budget)
- Positive integer: Fixed budget
  - Flash: 0-24,576
  - Pro: 128-32,768
  - Lite: 512-24,576

Important

Cannot be used with thinking_level in the same request.

Examples

# Disable thinking (save costs)
config = GenerationConfig.thinking_budget(0)

# Dynamic thinking (model decides)
config = GenerationConfig.thinking_budget(-1)

# Fixed budget (balance cost/quality)
config = GenerationConfig.thinking_budget(1024)

# Chain with other options
config =
  GenerationConfig.new()
  |> GenerationConfig.temperature(0.7)
  |> GenerationConfig.thinking_budget(2048)

thinking_config(config \\ %MODULE{}, budget, opts \\ [])

@spec thinking_config(t(), integer(), keyword()) :: t()

Set complete thinking configuration (budget + thoughts).

Convenience function to set both thinking budget and thought inclusion.

Parameters

config: GenerationConfig struct (defaults to new config)
budget: Thinking budget integer
opts: Keyword list with optional :include_thoughts boolean

Examples

# Set budget and enable thoughts
config = GenerationConfig.thinking_config(1024, include_thoughts: true)

# Just budget (thoughts disabled)
config = GenerationConfig.thinking_config(512)

thinking_level(config \\ %MODULE{}, level)

@spec thinking_level(
  t(),
  Gemini.Types.GenerationConfig.ThinkingConfig.thinking_level()
) :: t()

Set thinking level for Gemini 3 models.

Controls the depth of reasoning before the model responds.

Parameters

config: GenerationConfig struct (defaults to new config)
level: Thinking level atom
- :low - Minimizes latency and cost. Best for simple instruction following.
- :high - Maximizes reasoning depth. Model may take longer for first token.

Note: :medium is not currently supported by the API.

Important

Cannot be used with thinking_budget in the same request.

Examples

# Fast responses for simple tasks
config = GenerationConfig.thinking_level(:low)

# Deep reasoning for complex tasks (default)
config = GenerationConfig.thinking_level(:high)

# Chain with other options
config =
  GenerationConfig.new()
  |> GenerationConfig.thinking_level(:low)
  |> GenerationConfig.max_tokens(1000)