Configuration Types

Types for configuring API requests and behavior

Overview

Configuration types control various aspects of API requests, including generation parameters, HTTP options, and retry behavior.

GenerateContentConfig

Main configuration for content generation requests.

Generation Parameters

temperature · float

Controls randomness in token selection. Range: 0.0 to 2.0.

• Lower values (e.g., 0.2): More deterministic, focused responses
• Higher values (e.g., 1.5): More creative, diverse responses

top_p · float

Nucleus sampling parameter. Range: 0.0 to 1.0. Tokens are selected from smallest set whose cumulative probability exceeds top_p.

top_k · float

Number of highest probability tokens to consider at each step.

max_output_tokens · int

Maximum number of tokens in the response.

candidate_count · int

Number of response variations to generate.

stop_sequences · list[str]

List of strings that stop generation when encountered.

seed · int

Random seed for reproducible outputs.

Response Configuration

response_mime_type · str

Output format for the response.

• "text/plain": Plain text (default)
• "application/json": JSON response

response_schema · SchemaUnion

Schema object defining expected response structure. Use with response_mime_type="application/json".

response_json_schema · Any

JSON Schema for response validation. Alternative to response_schema with full JSON Schema support.

response_logprobs · bool

Whether to return log probabilities of chosen tokens.

logprobs · int

Number of top candidate tokens to return log probabilities for.

Instructions and Tools

system_instruction · ContentUnion

Instructions to steer model behavior (e.g., “Answer concisely”, “You are a helpful assistant”).

tools · ToolListUnion

List of tools the model can use (functions, code execution, search).

tool_config · ToolConfig

Configuration for tool usage and function calling.

automatic_function_calling · AutomaticFunctionCallingConfig

Configuration for automatic function calling.

Safety and Filtering

safety_settings · list[SafetySetting]

Safety settings to block unsafe content.

model_armor_config · ModelArmorConfig

Model Armor configuration for prompt/response sanitization. Cannot be used with safety_settings.

Media Configuration

media_resolution · MediaResolution

Default media resolution for all media in the request.

response_modalities · list[str]

Modalities the model can return (e.g., [“TEXT”, “IMAGE”, “AUDIO”]).

speech_config · SpeechConfigUnion

Configuration for speech generation.

audio_timestamp · bool

Whether to include audio timestamps in the request.

image_config · ImageConfig

Configuration for image generation.

Advanced Options

presence_penalty · float

Penalizes tokens that have appeared, encouraging diverse content.

frequency_penalty · float

Penalizes frequently repeated tokens.

thinking_config · ThinkingConfig

Configuration for model thinking/reasoning features.

routing_config · GenerationConfigRoutingConfig

Configuration for model routing.

model_selection_config · ModelSelectionConfig

Configuration for model selection.

cached_content · str

Resource name of cached content to use.

labels · dict[str, str]

User-defined metadata labels for billing breakdown.

http_options · HttpOptions

HTTP request options (see below).

should_return_http_response · bool

Whether to return raw HTTP response in sdk_http_response field.

Example

from google.genai.types import GenerateContentConfig

config = GenerateContentConfig(
    temperature=0.7,
    max_output_tokens=1024,
    top_p=0.95,
    top_k=40,
    stop_sequences=["END"],
    response_mime_type="application/json",
    system_instruction="You are a helpful assistant that responds in JSON format.",
    seed=42
)

response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="List 3 colors",
    config=config
)

HttpOptions

HTTP request configuration.

base_url · str

Base URL for the API endpoint.

base_url_resource_scope · ResourceScope

Resource scope for constructing resource names with custom base_url.

api_version · str

API version to use.

headers · dict[str, str]

Additional HTTP headers.

timeout · int

Request timeout in milliseconds.

client_args · dict[str, Any]

Arguments passed to the HTTP client.

async_client_args · dict[str, Any]

Arguments passed to the async HTTP client.

extra_body · dict[str, Any]

Extra parameters to add to the request body. Must match backend API structure.

retry_options · HttpRetryOptions

HTTP retry configuration (see below).

httpx_client · httpx.Client

Custom httpx client for requests.

httpx_async_client · httpx.AsyncClient

Custom httpx async client.

aiohttp_client · aiohttp.ClientSession

Custom aiohttp client session.

Example

from google.genai.types import HttpOptions

http_options = HttpOptions(
    timeout=30000,  # 30 seconds
    headers={"X-Custom-Header": "value"},
    retry_options={
        "attempts": 3,
        "initial_delay": 1.0
    }
)

config = GenerateContentConfig(
    temperature=0.5,
    http_options=http_options
)

HttpRetryOptions

Retry configuration for HTTP requests.

attempts · int

Maximum number of attempts including the original request. Default: 5. Set to 0 or 1 for no retries.

initial_delay · float

Initial delay before first retry in seconds. Default: 1.0.

max_delay · float

Maximum delay between retries in seconds. Default: 60.0.

exp_base · float

Exponential backoff multiplier. Default: 2.0.

jitter · float

Randomness factor for delay. Default: 1.0.

http_status_codes · list[int]

HTTP status codes that trigger a retry. Default: 408, 429, and 5xx errors.

Example

from google.genai.types import HttpRetryOptions

retry_options = HttpRetryOptions(
    attempts=5,
    initial_delay=1.0,
    max_delay=60.0,
    exp_base=2.0,
    jitter=0.5,
    http_status_codes=[408, 429, 500, 502, 503, 504]
)

http_options = HttpOptions(retry_options=retry_options)

Common Configuration Patterns

Creative Writing

config = GenerateContentConfig(
    temperature=1.2,
    top_p=0.95,
    top_k=50,
    max_output_tokens=2048
)

Deterministic Output

config = GenerateContentConfig(
    temperature=0.0,
    top_p=1.0,
    seed=12345,
    max_output_tokens=1024
)

JSON Response

from google.genai.types import GenerateContentConfig, Schema, Type

schema = Schema(
    type=Type.OBJECT,
    properties={
        "name": Schema(type=Type.STRING),
        "age": Schema(type=Type.INTEGER),
    },
    required=["name", "age"]
)

config = GenerateContentConfig(
    response_mime_type="application/json",
    response_schema=schema
)

With System Instructions

config = GenerateContentConfig(
    system_instruction="""You are a technical documentation expert.
    Provide clear, concise explanations with code examples.
    Use markdown formatting.""",
    temperature=0.3,
    max_output_tokens=2048
)

With Safety Settings

from google.genai.types import (
    GenerateContentConfig,
    SafetySetting,
    HarmCategory,
    HarmBlockThreshold
)

config = GenerateContentConfig(
    safety_settings=[
        SafetySetting(
            category=HarmCategory.HARM_CATEGORY_HARASSMENT,
            threshold=HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE
        ),
        SafetySetting(
            category=HarmCategory.HARM_CATEGORY_HATE_SPEECH,
            threshold=HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE
        )
    ]
)

With Custom Timeout

config = GenerateContentConfig(
    temperature=0.7,
    http_options=HttpOptions(
        timeout=60000,  # 60 seconds
        retry_options=HttpRetryOptions(attempts=3)
    )
)

See Also

• Types Overview - Type system overview
• Client Reference - Using config with the client
• Content Types - Content and Part types