Options

This page gives the per-request configuration model for individual model calls. Options use the functional options pattern.

Design: why functional options

Functional options such as WithTemperature and WithMaxTokens add new parameters without breaking callers. Options apply left to right. Later options override earlier options. Direct StreamText and GenerateText calls use this pattern. Agent-level defaults use it through WithStreamOpts.

Pointer semantics for defaults

Temperature and MaxTokens are *float64 and *int in the resolved StreamOptions. This distinguishes nil, meaning provider default, from a value explicitly set to zero. Providers test for nil and apply their own defaults.

Thinking levels

For models that support extended reasoning, WithThinking sets the thinking depth from minimal through xhigh. When set, the model produces Thinking content blocks alongside text. Not all providers support thinking. Unsupported levels are silently ignored or rejected, depending on the provider.

Tool choice

ToolChoice controls how the model selects tools. Values are auto for model choice, none for disabled tools, required for at least one tool, and SpecificToolChoice(name) for one named tool. auto is the default.

Cache retention

WithCacheRetention controls prompt-cache breakpoint placement and TTL across providers. It is on by default. The zero value resolves to CacheRetentionShort, so callers get cache hits without opting in. The four values are CacheRetentionDefault for unset to Short, CacheRetentionNone for disabled, and CacheRetentionShort for the provider’s default ephemeral TTL. CacheRetentionLong selects a longer ephemeral TTL where supported.

WithSessionID provides cache affinity for providers that support it. Currently, OpenAI Chat Completions and Responses forward it as prompt_cache_key. Other providers ignore it. The SDK does not auto-generate it. Callers pass a UUID when they want affinity across requests.

See Prompt Caching for the placement strategy and per-provider behavior.

Image options

WithImageSize, such as "1024x1024", and WithImageCount configure ai.GenerateImage. They ride on the same StreamOptions as every other option. Text and object calls ignore them. Providers map them to their own image APIs. OpenAI Images uses size and n directly. Imagen translates the size to an aspect ratio and uses the count as the number of images. An unsupported size falls back to a provider default.

Available options

WithTemperature, WithMaxTokens, WithThinking, WithToolChoice, WithCacheRetention, WithSessionID, WithHeaders, WithMetadata, WithImageSize, WithImageCount. See GoDoc for signatures.

Related

• Models — models carry default capabilities. Options override them per call
• Providers — providers receive the resolved StreamOptions
• Content — WithThinking enables Thinking content blocks
• Prompt Caching — WithCacheRetention and WithSessionID