What are ChatOptions in Spring AI and how do you apply them per-request?

ChatOptions is the interface through which you pass inference parameters — temperature, max tokens, top-p, stop sequences, model name — to the model for a specific call. Spring AI separates these from the core Prompt messages so they can be set at three different levels: default (in application.properties), per-client (on ChatClient.Builder), and per-request (on the individual call).

The general ChatOptions interface carries provider-agnostic fields like model, temperature, maxTokens, and topP. Provider-specific options (e.g. OpenAI's responseFormat, Anthropic's topK) are available on the concrete subclass.

// Per-request options — override the defaults for one call only
String creative = chatClient.prompt()
    .user("Write a haiku about Spring Boot.")
    .options(OpenAiChatOptions.builder()
        .withModel("gpt-4o")
        .withTemperature(0.9f)
        .withMaxTokens(60)
        .build())
    .call().content();

// Or use the provider-neutral interface for portability
String factual = chatClient.prompt()
    .user("List Java 21 features.")
    .options(ChatOptionsBuilder.builder()
        .withTemperature(0.1f)
        .build())
    .call().content();

Options set per-request override any defaults configured in properties or on the ChatClient.Builder. This layering lets you configure sensible defaults globally while still adjusting parameters for specific use cases — a creative writing endpoint might use temperature 0.9 while a factual Q&A endpoint uses 0.1 — without duplicating client configuration.