Configuration Types

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)
    )
)

Client

Models

Chats

Files

Caches

Tunings

Batches

Interactions (Beta)

Types

Overview

GenerateContentConfig

Generation Parameters

Response Configuration

Instructions and Tools

Safety and Filtering

Media Configuration

Advanced Options

Example

HttpOptions

Example

HttpRetryOptions

Example

Common Configuration Patterns

Creative Writing

Deterministic Output

JSON Response

With System Instructions

With Safety Settings

With Custom Timeout

See Also

Build docs developers (and LLMs) love

Client

Models

Chats

Files

Caches

Tunings

Batches

Interactions (Beta)

Types

​Overview

​GenerateContentConfig

​Generation Parameters

​Response Configuration

​Instructions and Tools

​Safety and Filtering

​Media Configuration

​Advanced Options

​Example

​HttpOptions

​Example

​HttpRetryOptions

​Example

​Common Configuration Patterns

​Creative Writing

​Deterministic Output

​JSON Response

​With System Instructions

​With Safety Settings

​With Custom Timeout

​See Also

Build docs developers (and LLMs) love

Overview

GenerateContentConfig

Generation Parameters

Response Configuration

Instructions and Tools

Safety and Filtering

Media Configuration

Advanced Options

Example

HttpOptions

Example

HttpRetryOptions

Example

Common Configuration Patterns

Creative Writing

Deterministic Output

JSON Response

With System Instructions

With Safety Settings

With Custom Timeout

See Also