spring ai azure openai gpt-5-thinking,Unknown parameter: 'reasoning'

[aixiangbaiyun]

Bug description

The reasoningEffort parameter in OpenAiChatOptions is being incorrectly serialized as "reasoning" instead of "reasoning_effort" when sent to the OpenAI API. This causes API requests to fail with an "Unknown parameter" error when using reasoning models like gpt-5-thinking (o1/o3 series).

According to OpenAI's API documentation, the correct parameter name should be reasoning_effort (with underscore), but Spring AI is sending it as reasoning (without the suffix).

Environment

• Spring AI version: 1.1.0-M4
• Spring Boot version: 3.3.13
• Java version: 17
• Model: Azure OpenAI gpt-5-thinking (also affects other reasoning models like o1, o1-mini, o1-preview, o3-mini)
• API Endpoint: Azure OpenAI Service (also affects standard OpenAI API)

Steps to reproduce

1. Configure OpenAiChatOptions with the reasoningEffort parameter:

ChatOptions options = OpenAiChatOptions.builder()
    .model("gpt-5-thinking")
    .temperature(0.0)
    .maxTokens(20000)
    .reasoningEffort("medium")  // low, medium, or high
    .build();

2. Make a chat completion request using the configured options

3. Observe the API error response

Expected behavior

The request should succeed, and the parameter should be serialized as "reasoning_effort": "medium" in the JSON payload sent to the OpenAI API.

Actual behavior

The request fails with the following error:

{
  "error": {
    "message": "Unknown parameter: 'reasoning'.",
    "type": "invalid_request_error",
    "param": "reasoning",
    "code": "unknown_parameter"
  }
}

This indicates that Spring AI is sending "reasoning" instead of "reasoning_effort".

Root Cause Analysis

The issue appears to be in the JSON serialization configuration of the OpenAiChatOptions class or related request objects. The reasoningEffort field likely lacks the proper @JsonProperty("reasoning_effort") annotation, causing Jackson to use the default camelCase field name instead of the API's expected snake_case format.

Minimal Complete Reproducible example

@Configuration
public class OpenAiConfig {
    
    @Bean
    public ChatClient chatClient(ChatModel chatModel) {
        ChatOptions options = OpenAiChatOptions.builder()
            .model("gpt-5-thinking")
            .temperature(0.0)
            .maxTokens(20000)
            .reasoningEffort("medium")  // This causes the error
            .build();
        
        return ChatClient.builder(chatModel)
            .defaultOptions(options)
            .build();
    }
}

@RestController
public class TestController {
    
    @Autowired
    private ChatClient chatClient;
    
    @GetMapping("/test")
    public String test() {
        // This will throw an exception due to the incorrect parameter name
        return chatClient.prompt()
            .user("Hello")
            .call()
            .content();
    }
}

Suggested Fix

Add the @JsonProperty("reasoning_effort") annotation to the reasoningEffort field in the relevant Spring AI OpenAI classes (likely in OpenAiChatOptions or the request DTO class).

Example:

@JsonProperty("reasoning_effort")
private String reasoningEffort;

Workaround

Currently, there is no workaround other than not using the reasoningEffort parameter, which limits the ability to control the reasoning depth of o1/o3 models.

References

• OpenAI API Documentation for reasoning models: The parameter should be reasoning_effort with values low, medium, or high
• This affects all OpenAI reasoning models that support the reasoning_effort parameter

[apappascs]

Thank you for reporting this issue. After a thorough investigation of the codebase, I can confirm that the Spring AI implementation is correct and the reasoning_effort parameter is properly serialized.

Validation Tests
I've added integration tests to validate the correct serialization of reasoning_effort: #4815

Code Verification

Both OpenAI implementations have the correct @JsonProperty("reasoning_effort") annotation:

1. OpenAiChatOptions.java:219

   @JsonProperty("reasoning_effort")
   private String reasoningEffort;
   

2. OpenAiApi.java:1130

@JsonProperty("reasoning_effort") String reasoningEffort,

3. AzureOpenAiChatOptions.java:258 (for Azure OpenAI)

@JsonProperty("reasoning_effort")
private String reasoningEffort;

The Azure implementation additionally converts the String to Azure SDK's ReasoningEffortValue enum in AzureOpenAiChatModel.merge() methods (lines 783-789 and 884-887), which
handles the actual serialization to the Azure API.

The Actual Issue: Invalid Model Name

The model name gpt-5-thinking mentioned in your report does not exist in either:

• https://platform.openai.com/docs/models
• https://ai.azure.com/catalog/models

[aixiangbaiyun]

Hello, thank you for taking the time to help me solve this problem. This gpt-5-thinking model comes from a proxy website at https://open.xiaojingai.com/. This model is their own wrapper implementation. When called, it uses the gpt-5 model, and the reasoning field contains the inference process. When accessing this model, it returns a reasoning field.

I also used this model for conversations in Cherry Studio, and from the results, I cannot see any reasoning process—only the model's response content. Logically speaking, since Cherry Studio can access it and get the correct output, the basic wrapper implementation should be fine. I suspect that in the Spring AI framework, this field might not be properly captured when the response is returned?

If you're willing, I can provide you with the proxy address and API key, or you can register an account yourself—there's also free quota available.

Thank you for reporting this issue. After a thorough investigation of the codebase, I can confirm that the Spring AI implementation is correct and the reasoning_effort parameter is properly serialized.

Validation Tests I've added integration tests to validate the correct serialization of reasoning_effort: #4815

Code Verification

Both OpenAI implementations have the correct @JsonProperty("reasoning_effort") annotation:

1. OpenAiChatOptions.java:219
   @JsonProperty("reasoning_effort")
   private String reasoningEffort;
2. OpenAiApi.java:1130

@JsonProperty("reasoning_effort") String reasoningEffort,

3. AzureOpenAiChatOptions.java:258 (for Azure OpenAI)

@JsonProperty("reasoning_effort")
private String reasoningEffort;

The Azure implementation additionally converts the String to Azure SDK's ReasoningEffortValue enum in AzureOpenAiChatModel.merge() methods (lines 783-789 and 884-887), which handles the actual serialization to the Azure API.

The Actual Issue: Invalid Model Name

The model name gpt-5-thinking mentioned in your report does not exist in either:

• https://platform.openai.com/docs/models
• https://ai.azure.com/catalog/models

Hello, thank you for taking the time to help me solve this problem. This gpt-5-thinking model comes from a proxy website at https://open.xiaojingai.com/.
This model is their own wrapper implementation. When called, it uses the gpt-5 model, and the reasoning field contains the inference process. When accessing this model, it returns a reasoning field.
I also used this model for conversations in Cherry Studio, and from the results, I cannot see any reasoning process—only the model's response content.
Logically speaking, since Cherry Studio can access it and get the correct output, the basic wrapper implementation should be fine. I suspect that in the Spring AI framework, this field might not be properly captured when the response is returned?
If you're willing, I can provide you with the proxy address and API key, or you can register an account yourself—there's also free quota available.

[ilayaperumalg]

@apappascs Thanks for helping out with the issue by investigating and subsequently submitting the PR with tests.

I can also confirm that the Spring AI OpenAiChatOptions is correctly configured with the @JsonProperty for "reasoning_effort" and I just verified the same from #4815.

@aixiangbaiyun You may have to improve your prompt as in some cases the model doesn't seem to use the reasoning if the prompt is simple enough. For instance, in your prompt, add something like "Think through the steps and respond" . This can help the model to include the reasoning. Also, you can try increasing the reasoning level to "high" to verify.

[apappascs]

if I understood correctly there is no ERROR then but the reasoning process field is missing on the response context?

Spring AI implements the chat completion api of openAI https://platform.openai.com/docs/api-reference/chat/create
and the response of it does not include any reasoning field https://platform.openai.com/docs/api-reference/chat/object

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_fc9f1d7035"
}

I guess the wrapper you mentioned and cherry ai are using the responses api endpoint which includes the reasoning field:

https://platform.openai.com/docs/api-reference/responses/object

[aixiangbaiyun]

如果我理解正确，那么没有错误，但在响应上下文中缺少？reasoning process field

Spring AI 实现了 openAI https://platform.openai.com/docs/api-reference/chat/create 的聊天补全 api，其响应不包含任何推理字段 https://platform.openai.com/docs/api-reference/chat/object

{
  "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG",
  "object": "chat.completion",
  "created": 1741570283,
  "model": "gpt-4o-2024-08-06",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.",
        "refusal": null,
        "annotations": []
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1117,
    "completion_tokens": 46,
    "total_tokens": 1163,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "audio_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  },
  "service_tier": "default",
  "system_fingerprint": "fp_fc9f1d7035"
}

我猜你提到的包装器和 cherry ai 正在使用响应 api 端点，其中包括推理字段：

https://platform.openai.com/docs/api-reference/responses/object

You're absolutely right.
From my perspective, Spring AI doesn't have any issues, but the [gpt-5-thinking] reasoning model wrapped by this proxy platform returns a field called "reasoning", and I believe this unexpected parameter cannot be handled by Spring AI.
Do you think this is a problem? From my usage perspective, why doesn't Cherry Studio have this issue? That's why I reported this problem.
If you don't think it's a problem, I'll close this feedback. Here is the proxy address https://open.xiaojingai.com, and an API key with $0.5 credit: sk-hHBeiBRO3RGX3b6FGdumnlfa1htjbJ14K7ehW8LzLcDQiNq4. If you're interested, you can try it out.

[apappascs]

@aixiangbaiyun

Please make sure to remove your API key from the message! it’s not safe to expose it publicly.

Since Spring AI follows the official OpenAI chat completion schema, that unexpected field isn’t recognized or mapped.

Cherry Studio doesn’t have this issue because it treats provider responses more loosely and doesn’t rely on strong typing, so new or additional fields don’t cause deserialization errors.

From Spring AI’s side, this isn’t technically a bug. it’s a schema mismatch caused by the proxy returning fields outside of the OpenAI spec.

[aixiangbaiyun]

@aixiangbaiyun

Please make sure to remove your API key from the message! it’s not safe to expose it publicly.

Since Spring AI follows the official OpenAI chat completion schema, that unexpected field isn’t recognized or mapped.

Cherry Studio doesn’t have this issue because it treats provider responses more loosely and doesn’t rely on strong typing, so new or additional fields don’t cause deserialization errors.

From Spring AI’s side, this isn’t technically a bug. it’s a schema mismatch caused by the proxy returning fields outside of the OpenAI spec.

Don't worry, this API key has only a 0.50 balance and will expire tomorrow night. It was created specifically to help you identify issues. In fact, I believe that with so many people around the world using AI, proxies have become a common way to overcome regional restrictions. To improve access, some proxy platforms may indeed wrap request parameters and return unexpected fields. Do you think it would make sense to add a switch in spring-ai so it can handle these unexpected fields more leniently?

[apappascs]

I will try my best to explain even tho this is not tied to Spring AI.

Type safety is a feature, not a bug. Java developers choose Java specifically for reliability and predictability. If you want loose typing, use Python/JavaScript. "Works with everything" often means "fails unpredictably."

Spring AI is right to strictly follow OpenAI's official specification because:

• Type Safety: Strong typing prevents silent failures and makes bugs obvious
• Maintainability: Supporting every non-standard proxy would be a nightmare
• Security: Loose parsing can introduce vulnerabilities (imagine a proxy injecting "execute_code": "rm -rf /" that gets silently ignored)
• Standards Compliance: Following the spec ensures compatibility with official APIs

Why lenient mode is problematic:

• Creates technical debt
• Different proxies have different customizations
• Encourages non-standard implementations
• Masks real bugs and API changes

Cherry Studio sacrifices type safety for flexibility which is not necessarily better design