atlas by clearpeople

Overwriting Azure OpenAI API api-version property using Semantic Kernel


As you have seen in my previous articles, we are doing a ton of work around Azure OpenAI. When dealing with OpenAI, I truly recommend the use of the open source library Semantic Kernel (

A few days ago, we got an email from Microsoft, announcing the deprecation of multiple API Versions. In case you don’t know, when calling Azure OpenAI API, the URL looks like this:

https://{service_name}{deployment_name} /chat/completions?api-version=2023-03-15-preview

As you see, there is an api-version query string at the end, with a specific value. This query string is required, and you need to set a valid version, otherwise you will get a 404 error.

According to MS email, here are the deprecated values:

  • 2023-03-15-preview
  • 2023-06-01-preview
  • 2023-07-01-preview
  • 2023-08-01-preview
  • 2023-09-15-preview

And here is a link to a MS article about this:

If you look to the article, you might – like I was - be surprised to see that it shows a different set of deprecated versions compared to the email. We have been trying to get an official answer from MS, with no response so far.

According to the email, the latest version is 2023-12-01-preview, and they recommend you update your code to use that version.

But how then, to update to that version? The thing is that if you are using Semantic Kernel, it’s the library which is calling Azure OpenAI API and setting that api-version value. To be very precise, is actually not even the Semantic Kernel, but specifically the Azure.AI.OpenAI SDK ( which is calling the API.

You can see the value used by the SDK in the file: sdk/openai/Azure.AI.OpenAI/src/Generated/OpenAIClientOptions.cs

OpenAI Service Versions

As you can see, the latest version of the SDK, is already using the latest api-version value.

So, we are all good, yes? You just need to update the Semantic Kernel package to latest version, and you are good… and a bit lucky.

If you are less lucky however, then your solution has other dependencies, making it less easy.

For instance, if we take a look to the dependencies of the Microsoft.SemanticKernel.Abstractions package, among others, it depends on:

If your solution has some Azure Functions v4 In-proc, working with .NET 6, the previous dependencies are going to be an issue.


But – don’t panic! If you are somehow in this scenario, the following trick should solve your issue, as it did for us.

Semantic Kernel has a nice feature that allows you to provide a specific HttpClient that the library will use when calling Azure OpenAI. You can create a custom Delegating handler that checks the api-version value and replaces it with the latest one.

Here is the code:


Before creating the Kernel, we create a custom HttpClient which will use the previous Handler, and it will pass that client object to the Kernel creation. This is illustrated in the POC sample code below. Note: DO NOT create the HttpClient in the way shown, as it is just a POC in a console app which is good enough to illustrate the concept. Instead, use a HttpClient Factory.


That’s all. With this approach, you can update the api-version without the need to update the entire Semantic Kernel package.

Hope it helps!

Author bio

Luis Mañez

Luis Mañez

Luis is Atlas Chief Architect. He is also a Microsoft 365 Development MVP and SharePoint and Cloud Solutions architect. "I help find the best technical designs to meet client needs and act as tech lead to build great solutions. I have fun with some R&D tasks, always trying to improve our tools and processes, and I often help the Microsoft community as a blogger and speaker, contributing to open-source projects."

View all articles by this author View all articles by this author

Get our latest posts in your inbox