Fix extraBody not being included in OpenAI API requests

Two issues prevented extraBody from reaching the HTTP request:

1. Options→Request merge: ChatCompletionRequest.extraBody lacked
   @JsonProperty annotation, causing ModelOptionsUtils.merge() to
   filter it out. Added @JsonProperty("extra_body") annotation.

2. Options→Options merge: ModelOptionsUtils.merge() replaces the
   entire extraBody map instead of merging keys, causing default
   values to be lost when runtime options also specify extraBody.
   Added explicit mergeExtraBody() method to properly combine maps
   with runtime values taking precedence.

Added wire-level and unit tests to verify end-to-end behavior.

Author: CorgiBoyG

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatModel.java

@@ -548,13 +548,16 @@ Prompt buildRequestPrompt(Prompt prompt) {
 					this.defaultOptions.getToolCallbacks()));
 			requestOptions.setToolContext(ToolCallingChatOptions.mergeToolContext(runtimeOptions.getToolContext(),
 					this.defaultOptions.getToolContext()));
+			requestOptions
+				.setExtraBody(mergeExtraBody(runtimeOptions.getExtraBody(), this.defaultOptions.getExtraBody()));
 		}
 		else {
 			requestOptions.setHttpHeaders(this.defaultOptions.getHttpHeaders());
 			requestOptions.setInternalToolExecutionEnabled(this.defaultOptions.getInternalToolExecutionEnabled());
 			requestOptions.setToolNames(this.defaultOptions.getToolNames());
 			requestOptions.setToolCallbacks(this.defaultOptions.getToolCallbacks());
 			requestOptions.setToolContext(this.defaultOptions.getToolContext());
+			requestOptions.setExtraBody(this.defaultOptions.getExtraBody());
 		}
 
 		ToolCallingChatOptions.validateToolCallbacks(requestOptions.getToolCallbacks());
@@ -569,6 +572,21 @@ private Map<String, String> mergeHttpHeaders(Map<String, String> runtimeHttpHead
 		return mergedHttpHeaders;
 	}
 
+	private Map<String, Object> mergeExtraBody(Map<String, Object> runtimeExtraBody,
+			Map<String, Object> defaultExtraBody) {
+		if (defaultExtraBody == null && runtimeExtraBody == null) {
+			return null;
+		}
+		var merged = new HashMap<String, Object>();
+		if (defaultExtraBody != null) {
+			merged.putAll(defaultExtraBody);
+		}
+		if (runtimeExtraBody != null) {
+			merged.putAll(runtimeExtraBody); // runtime overrides default
+		}
+		return merged.isEmpty() ? null : merged;
+	}
+
 	/**
 	 * Accessible for testing.
 	 */

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/api/OpenAiApi.java

@@ -1139,7 +1139,7 @@ public record ChatCompletionRequest(// @formatter:off
 			@JsonProperty("verbosity") String verbosity,
 			@JsonProperty("prompt_cache_key") String promptCacheKey,
 			@JsonProperty("safety_identifier") String safetyIdentifier,
-			Map<String, Object> extraBody) {
+			@JsonProperty("extra_body") Map<String, Object> extraBody) {
 
 		/**
 		 * Compact constructor that ensures extraBody is initialized as a mutable HashMap

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/ChatCompletionRequestTests.java

@@ -162,6 +162,70 @@ void defaultOptionsTools() {
 		assertThat(request.tools().get(0).getFunction().getName()).isEqualTo(TOOL_FUNCTION_NAME);
 	}
 
+	@Test
+	void extraBodyIsMergedIntoRequest() {
+		var client = OpenAiChatModel.builder()
+			.openAiApi(OpenAiApi.builder().apiKey("TEST").build())
+			.defaultOptions(OpenAiChatOptions.builder()
+				.model("gpt-4")
+				.extraBody(Map.of("default_key", "default_value", "shared_key", "default"))
+				.build())
+			.build();
+
+		var prompt = client.buildRequestPrompt(new Prompt("Test",
+				OpenAiChatOptions.builder()
+					.extraBody(Map.of("runtime_key", "runtime_value", "shared_key", "runtime"))
+					.build()));
+
+		var request = client.createRequest(prompt, false);
+
+		// Verify extraBody is present in the request
+		assertThat(request.extraBody()).isNotNull();
+		// Default key should be present
+		assertThat(request.extraBody()).containsEntry("default_key", "default_value");
+		// Runtime key should be present
+		assertThat(request.extraBody()).containsEntry("runtime_key", "runtime_value");
+		// Runtime should override default for shared key
+		assertThat(request.extraBody()).containsEntry("shared_key", "runtime");
+	}
+
+	@Test
+	void extraBodyFromDefaultOptionsOnly() {
+		var client = OpenAiChatModel.builder()
+			.openAiApi(OpenAiApi.builder().apiKey("TEST").build())
+			.defaultOptions(OpenAiChatOptions.builder()
+				.model("gpt-4")
+				.extraBody(Map.of("top_k", 50, "repetition_penalty", 1.1))
+				.build())
+			.build();
+
+		var prompt = client.buildRequestPrompt(new Prompt("Test"));
+
+		var request = client.createRequest(prompt, false);
+
+		// Verify extraBody from default options is present
+		assertThat(request.extraBody()).isNotNull();
+		assertThat(request.extraBody()).containsEntry("top_k", 50);
+		assertThat(request.extraBody()).containsEntry("repetition_penalty", 1.1);
+	}
+
+	@Test
+	void extraBodyFromRuntimeOptionsOnly() {
+		var client = OpenAiChatModel.builder()
+			.openAiApi(OpenAiApi.builder().apiKey("TEST").build())
+			.defaultOptions(OpenAiChatOptions.builder().model("gpt-4").build())
+			.build();
+
+		var prompt = client.buildRequestPrompt(
+				new Prompt("Test", OpenAiChatOptions.builder().extraBody(Map.of("enable_thinking", true)).build()));
+
+		var request = client.createRequest(prompt, false);
+
+		// Verify extraBody from runtime options is present
+		assertThat(request.extraBody()).isNotNull();
+		assertThat(request.extraBody()).containsEntry("enable_thinking", true);
+	}
+
 	static class TestToolCallback implements ToolCallback {
 
 		private final ToolDefinition toolDefinition;

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/api/ExtraBodySerializationTest.java

@@ -22,6 +22,8 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.Test;
 
+import org.springframework.ai.model.ModelOptionsUtils;
+import org.springframework.ai.openai.OpenAiChatOptions;
 import org.springframework.ai.openai.api.OpenAiApi.ChatCompletionRequest;
 
 import static org.assertj.core.api.Assertions.assertThat;
@@ -208,4 +210,25 @@ void testDeserializationWithComplexExtraFields() throws Exception {
 		assertThat(request.extraBody().get("stop_token_ids")).isInstanceOf(List.class);
 	}
 
+	@Test
+	void testMergeWithExtraBody() throws Exception {
+		// Arrange: Create OpenAiChatOptions with extraBody
+		OpenAiChatOptions requestOptions = OpenAiChatOptions.builder()
+			.model("test-model")
+			.extraBody(Map.of("enable_thinking", true, "max_depth", 10))
+			.build();
+
+		// Create empty ChatCompletionRequest
+		ChatCompletionRequest request = new ChatCompletionRequest(null, null);
+
+		// Act: Merge options into request
+		request = ModelOptionsUtils.merge(requestOptions, request, ChatCompletionRequest.class);
+
+		// Assert: Verify extraBody was successfully merged
+		assertThat(request.extraBody()).isNotNull();
+		assertThat(request.extraBody()).containsEntry("enable_thinking", true);
+		assertThat(request.extraBody()).containsEntry("max_depth", 10);
+		assertThat(request.model()).isEqualTo("test-model");
+	}
+
 }

models/spring-ai-openai/src/test/java/org/springframework/ai/openai/chat/ExtraBodyWireTest.java

@@ -0,0 +1,230 @@
+/*
+ * Copyright 2023-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.openai.chat;
+
+import java.util.Map;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import okhttp3.mockwebserver.MockResponse;
+import okhttp3.mockwebserver.MockWebServer;
+import okhttp3.mockwebserver.RecordedRequest;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import org.springframework.ai.chat.prompt.Prompt;
+import org.springframework.ai.openai.OpenAiChatModel;
+import org.springframework.ai.openai.OpenAiChatOptions;
+import org.springframework.ai.openai.api.OpenAiApi;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Test to verify that extraBody parameters are correctly included in the HTTP request
+ * sent to the OpenAI API. This test captures the actual wire-level JSON to verify the
+ * end-to-end flow from OpenAiChatOptions through to the HTTP request body.
+ *
+ * <p>
+ * These tests ensure that extraBody fields are:
+ * <ul>
+ * <li>Correctly merged from OpenAiChatOptions into ChatCompletionRequest</li>
+ * <li>Flattened to the top level of the JSON (not nested under "extra_body")</li>
+ * <li>Properly handled when set in default options, runtime options, or both</li>
+ * </ul>
+ *
+ * @author Mark Pollack
+ * @see <a href="https://github.com/spring-projects/spring-ai/issues/4867">GitHub Issue
+ * #4867</a>
+ */
+class ExtraBodyWireTest {
+
+	private MockWebServer mockWebServer;
+
+	private final ObjectMapper objectMapper = new ObjectMapper();
+
+	@BeforeEach
+	void setUp() throws Exception {
+		this.mockWebServer = new MockWebServer();
+		this.mockWebServer.start();
+	}
+
+	@AfterEach
+	void tearDown() throws Exception {
+		this.mockWebServer.shutdown();
+	}
+
+	@Test
+	void extraBodyFromRuntimeOptionsAppearsInHttpRequest() throws Exception {
+		// Arrange: Mock response
+		this.mockWebServer.enqueue(createMockResponse());
+
+		OpenAiApi api = OpenAiApi.builder().apiKey("test-key").baseUrl(this.mockWebServer.url("/").toString()).build();
+
+		OpenAiChatModel chatModel = OpenAiChatModel.builder()
+			.openAiApi(api)
+			.defaultOptions(OpenAiChatOptions.builder().model("gpt-4").build())
+			.build();
+
+		// Act: Call with extraBody in runtime options
+		OpenAiChatOptions runtimeOptions = OpenAiChatOptions.builder()
+			.extraBody(Map.of("top_k", 50, "repetition_penalty", 1.1))
+			.build();
+
+		chatModel.call(new Prompt("Hello", runtimeOptions));
+
+		// Assert: Verify the wire-level JSON contains flattened extraBody fields
+		RecordedRequest recordedRequest = this.mockWebServer.takeRequest();
+		String requestBody = recordedRequest.getBody().readUtf8();
+		JsonNode json = this.objectMapper.readTree(requestBody);
+
+		// Verify extraBody fields are at top level
+		assertThat(json.has("top_k")).as("top_k should be at top level").isTrue();
+		assertThat(json.get("top_k").asInt()).isEqualTo(50);
+		assertThat(json.has("repetition_penalty")).as("repetition_penalty should be at top level").isTrue();
+		assertThat(json.get("repetition_penalty").asDouble()).isEqualTo(1.1);
+
+		// Verify extra_body is NOT a nested object (fields are flattened)
+		assertThat(json.has("extra_body")).as("extra_body should NOT appear as nested object").isFalse();
+	}
+
+	@Test
+	void extraBodyFromDefaultOptionsAppearsInHttpRequest() throws Exception {
+		// Arrange: Mock response
+		this.mockWebServer.enqueue(createMockResponse());
+
+		OpenAiApi api = OpenAiApi.builder().apiKey("test-key").baseUrl(this.mockWebServer.url("/").toString()).build();
+
+		// Set extraBody in DEFAULT options
+		OpenAiChatModel chatModel = OpenAiChatModel.builder()
+			.openAiApi(api)
+			.defaultOptions(OpenAiChatOptions.builder()
+				.model("gpt-4")
+				.extraBody(Map.of("enable_thinking", true, "top_k", 40))
+				.build())
+			.build();
+
+		// Act: Call without runtime options
+		chatModel.call(new Prompt("Hello"));
+
+		// Assert: Verify wire-level JSON
+		RecordedRequest recordedRequest = this.mockWebServer.takeRequest();
+		String requestBody = recordedRequest.getBody().readUtf8();
+		JsonNode json = this.objectMapper.readTree(requestBody);
+
+		assertThat(json.has("enable_thinking")).isTrue();
+		assertThat(json.get("enable_thinking").asBoolean()).isTrue();
+		assertThat(json.has("top_k")).isTrue();
+		assertThat(json.get("top_k").asInt()).isEqualTo(40);
+
+		// Verify extra_body is NOT a nested object
+		assertThat(json.has("extra_body")).as("extra_body should NOT appear as nested object").isFalse();
+	}
+
+	@Test
+	void runtimeExtraBodyOverridesDefaultExtraBody() throws Exception {
+		// Arrange
+		this.mockWebServer.enqueue(createMockResponse());
+
+		OpenAiApi api = OpenAiApi.builder().apiKey("test-key").baseUrl(this.mockWebServer.url("/").toString()).build();
+
+		OpenAiChatModel chatModel = OpenAiChatModel.builder()
+			.openAiApi(api)
+			.defaultOptions(OpenAiChatOptions.builder()
+				.model("gpt-4")
+				.extraBody(Map.of("top_k", 40, "default_only", "value"))
+				.build())
+			.build();
+
+		// Act: Runtime extraBody should override default for same key
+		OpenAiChatOptions runtimeOptions = OpenAiChatOptions.builder()
+			.extraBody(Map.of("top_k", 100, "runtime_only", "value"))
+			.build();
+
+		chatModel.call(new Prompt("Hello", runtimeOptions));
+
+		// Assert
+		RecordedRequest recordedRequest = this.mockWebServer.takeRequest();
+		String requestBody = recordedRequest.getBody().readUtf8();
+		JsonNode json = this.objectMapper.readTree(requestBody);
+
+		// Runtime overrides default
+		assertThat(json.get("top_k").asInt()).isEqualTo(100);
+		// Both unique keys present
+		assertThat(json.has("default_only")).isTrue();
+		assertThat(json.has("runtime_only")).isTrue();
+
+		// Verify extra_body is NOT a nested object
+		assertThat(json.has("extra_body")).as("extra_body should NOT appear as nested object").isFalse();
+	}
+
+	@Test
+	void extraBodyWithVllmParameters() throws Exception {
+		// Arrange: Test with real vLLM parameters
+		this.mockWebServer.enqueue(createMockResponse());
+
+		OpenAiApi api = OpenAiApi.builder().apiKey("test-key").baseUrl(this.mockWebServer.url("/").toString()).build();
+
+		OpenAiChatModel chatModel = OpenAiChatModel.builder()
+			.openAiApi(api)
+			.defaultOptions(OpenAiChatOptions.builder().model("meta-llama/Llama-3-8B-Instruct").build())
+			.build();
+
+		// Act: Use real vLLM parameters
+		OpenAiChatOptions runtimeOptions = OpenAiChatOptions.builder()
+			.extraBody(Map.of("top_k", 50, "min_p", 0.05, "repetition_penalty", 1.1, "best_of", 3))
+			.build();
+
+		chatModel.call(new Prompt("Hello", runtimeOptions));
+
+		// Assert
+		RecordedRequest recordedRequest = this.mockWebServer.takeRequest();
+		String requestBody = recordedRequest.getBody().readUtf8();
+		JsonNode json = this.objectMapper.readTree(requestBody);
+
+		// All vLLM parameters should be at top level
+		assertThat(json.get("top_k").asInt()).isEqualTo(50);
+		assertThat(json.get("min_p").asDouble()).isEqualTo(0.05);
+		assertThat(json.get("repetition_penalty").asDouble()).isEqualTo(1.1);
+		assertThat(json.get("best_of").asInt()).isEqualTo(3);
+
+		// Verify model is also set correctly
+		assertThat(json.get("model").asText()).isEqualTo("meta-llama/Llama-3-8B-Instruct");
+	}
+
+	private MockResponse createMockResponse() {
+		return new MockResponse().setResponseCode(200)
+			.addHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
+			.setBody("""
+					{
+						"id": "chatcmpl-123",
+						"object": "chat.completion",
+						"created": 1677652288,
+						"model": "gpt-4",
+						"choices": [{
+							"index": 0,
+							"message": {"role": "assistant", "content": "Hello!"},
+							"finish_reason": "stop"
+						}],
+						"usage": {"prompt_tokens": 9, "completion_tokens": 2, "total_tokens": 11}
+					}
+					""");
+	}
+
+}