This article shows you how to use the v1 Azure OpenAI API. The v1 API simplifies authentication, removes the need for dated api-version parameters, and supports cross-provider model calls.

Prerequisites

• An Azure subscription - Create one for free
• A Foundry resource or Azure OpenAI resource deployed in a supported region
• At least one model deployment
• For Microsoft Entra ID authentication: the Cognitive Services OpenAI User role assigned to your identity. For more information, see Role-based access control for Azure OpenAI

API evolution

Previously, Azure OpenAI received monthly updates of new API versions. Taking advantage of new features required constantly updating code and environment variables with each new API release. Azure OpenAI also required the extra step of using Azure specific clients which created overhead when migrating code between OpenAI and Azure OpenAI.

Starting in August 2025, you can opt in to the next generation v1 Azure OpenAI APIs which add support for:

• Ongoing access to the latest features with no need to specify new api-version's each month.
• Faster API release cycle with new features launching more frequently.
• OpenAI client support with minimal code changes to swap between OpenAI and Azure OpenAI when using key-based authentication.
• OpenAI client support for token based authentication and automatic token refresh without the need to take a dependency on a separate Azure OpenAI client.
• Make chat completions calls with models from other providers like DeepSeek and Grok which support the v1 chat completions syntax.

Access to new API calls that are still in preview is controlled by passing feature specific preview headers. This approach allows you to opt in to the features you want, without having to swap API versions. Alternatively, some features indicate preview status through their API path and don't require an additional header.

Examples:

• When /openai/v1/evals was previously in preview, it required passing an "aoai-evals":"preview" header. /evals is no longer in preview.
• /openai/v1/fine_tuning/alpha/graders/ is in preview and requires no custom header due to the presence of alpha in the API path.

For the initial v1 Generally Available (GA) API launch, only a subset of the inference and authoring API capabilities are supported. All GA features are supported for use in production. Support for more capabilities is being added rapidly.

Code changes

Python

v1 API

Python v1 examples

API Key:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

response = client.responses.create(   
  model="gpt-4.1-nano", # Replace with your model deployment name 
  input="This is a test.",
)

print(response.model_dump_json(indent=2)) 

Key differences from the previous API:

• OpenAI() client is used instead of AzureOpenAI().
• Pass the Azure OpenAI endpoint to base_url and append /openai/v1 to the endpoint address.
• api-version is no longer a required parameter with the v1 GA API.

API Key with environment variables:

Set the following environment variables before running the code:

Variable	Value
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	Your Azure OpenAI API key

Then create the client without parameters:

client = OpenAI()

Microsoft Entra ID:

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key = token_provider  
)

response = client.responses.create(
    model="gpt-4.1-nano",
    input= "This is a test" 
)

print(response.model_dump_json(indent=2)) 

• Pass the Azure OpenAI endpoint to base_url and append /openai/v1 to the endpoint address.
• Set the api_key parameter to token_provider to enable automatic retrieval and refresh of an authentication token instead of using a static API key.

C#

v1 API

C# v1 examples

API Key:

OpenAIClient client = new(
    new ApiKeyCredential("{your-api-key}"),
    new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

Microsoft Entra ID:

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");
OpenAIClient client = new(
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

JavaScript

v1 API

JavaScript v1 examples

API Key:

const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: "{your-api-key}" 
});

API Key with environment variables set for OPENAI_BASE_URL and OPENAI_API_KEY:

const client = new OpenAI();

Microsoft Entra ID:

const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

Go

v1 API

Go v1 examples

API Key:

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    option.WithAPIKey("{your-api-key}")
)

API Key with environment variables set for OPENAI_BASE_URL and OPENAI_API_KEY:

client := openai.NewClient()

Microsoft Entra ID:

tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    azure.WithTokenCredential(tokenCredential)
)

Java

Java v1 examples

v1 API

API Key:

OpenAIClient client = OpenAIOkHttpClient.builder()
                .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
                .apiKey(apiKey)
                .build();

API Key with environment variables set for OPENAI_BASE_URL and OPENAI_API_KEY:

OpenAIClient client = OpenAIOkHttpClient.builder()
                .fromEnv()
                .build();

Microsoft Entra ID:

Credential tokenCredential = BearerTokenCredential.create(
        AuthenticationUtil.getBearerTokenSupplier(
                new DefaultAzureCredentialBuilder().build(),
                "https://ai.azure.com/.default"));
OpenAIClient client = OpenAIOkHttpClient.builder()
        .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
        .credential(tokenCredential)
        .build();

REST

v1 API

API Key:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
     "model": "gpt-4.1-nano",
     "input": "This is a test"
    }'

Microsoft Entra ID:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4o",
     "input": "This is a test"
    }'

---

Model support

For Azure OpenAI models we recommend using the Responses API, however, the v1 API also allows you to make chat completions calls with models from other providers like DeepSeek and Grok which support the OpenAI v1 chat completions syntax.

base_url accepts both https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ and https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ formats.

Python

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

client = OpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)
completion = client.chat.completions.create(
  model="MAI-DS-R1", # Replace with your model deployment name.
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Tell me about the attention is all you need paper"}
  ]
)

#print(completion.choices[0].message)
print(completion.model_dump_json(indent=2))

C#

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "MAI-DS-R1", // Replace with your model deployment name.
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions() { 
    
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
   }
);

ChatCompletion completion = client.CompleteChat("Tell me about the attention is all you need paper");

Console.WriteLine($"[ASSISTANT]: {completion.Content[0].Text}");

JavaScript

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import OpenAI from "openai";

const endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/";
const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const openai = new OpenAI({
    baseURL: endpoint,
    apiKey: tokenProvider
});

async function main() {
    const result = await openai.chat.completions.create({
        model: "MAI-DS-R1", // Replace with your model deployment name.
        messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: "Explain the attention mechanism." }
        ]
    });
    console.log(result.choices[0]?.message.content ?? "No response returned.");
}

main().catch(console.error);

Go

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/azure"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	// Create an Azure credential
	tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("Failed to create credential: %s", err)
	}

	// Create a client with Azure OpenAI endpoint and token credential
	client := openai.NewClient(
		option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
		azure.WithTokenCredential(tokenCredential),
	)

	// Make a completion request
	chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Explain what the bitter lesson is?"),
		},
		Model: "MAI-DS-R1", // Use your deployed model name on Azure
	})
	if err != nil {
		log.Fatalf("Failed to get chat completions: %s", err)
	}

	fmt.Println(chatCompletion.Choices[0].Message.Content)
}

Java

package com.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class OpenAITest {
    public static void main(String[] args) {
        // Get API key from environment variable for security
        String apiKey = System.getenv("OPENAI_API_KEY");
        String resourceName = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1";
        String modelDeploymentName = "MAI-DS-R1"; //replace with your model deployment name

        try {
            OpenAIClient client = OpenAIOkHttpClient.builder()
                    .baseUrl(resourceName)
                    .apiKey(apiKey)
                    .build();

           ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
              .addUserMessage("Explain what the bitter lesson is?")
              .model(modelDeploymentName)
              .build();
           ChatCompletion chatCompletion = client.chat().completions().create(params);
        }
    }
}

REST

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
      "model": "MAI-DS-R1",
      "messages": [
      {
        "role": "developer",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain what the bitter lesson is?"
      }
    ]
  }'

---

v1 API support

• v1 OpenAPI 3.0 spec

API version changelog

The following sections summarize changes between API versions.

Changes between v1 preview release and 2025-04-01-preview

• v1 preview API
• Video generation support
• NEW Responses API features:
  • Remote Model Context Protocol (MCP) servers tool integration
  • Support for asynchronous background tasks
  • Encrypted reasoning items
  • Image generation

Changes between 2025-04-01-preview and 2025-03-01-preview

• GPT-image-1 support
• Reasoning summary for o3 and o4-mini
• Evaluation API

Changes between 2025-03-01-preview and 2025-02-01-preview

• Responses API
• Computer use

Changes between 2025-02-01-preview and 2025-01-01-preview

• Stored completions (distillation API support).

Changes between 2025-01-01-preview and 2024-12-01-preview

• prediction parameter added for predicted outputs support.
• gpt-4o-audio-preview model support.

Changes between 2024-12-01-preview and 2024-10-01-preview

• store, and metadata parameters added for stored completions support.
• reasoning_effort added for latest reasoning models.
• user_security_context added for Microsoft Defender for Cloud integration.

Changes between 2024-09-01-preview and 2024-08-01-preview

• max_completion_tokens added to support o1-preview and o1-mini models. max_tokens doesn't work with the o1 series models.
• parallel_tool_calls added.
• completion_tokens_details & reasoning_tokens added.
• stream_options & include_usage added.

Changes between 2024-07-01-preview and 2024-08-01-preview API specification

• Structured outputs support.
• Large file upload API added.
• On your data changes:
  • Mongo DB integration.
  • role_information parameter removed.
  • rerank_score added to citation object.
  • AML datasource removed.
  • AI Search vectorization integration improvements.

Changes between 2024-05-01-preview and 2024-07-01-preview API specification

• Batch API support added.
• Vector store chunking strategy parameters.
• max_num_results that the file search tool should output.

Changes between 2024-04-01-preview and 2024-05-01-preview API specification

• Assistants v2 support - File search tool and vector storage
• Fine-tuning checkpoints, seed, events
• On your data updates
• DALL-E 2 now supports model deployment and can be used with the latest preview API.
• Content filtering updates

Changes between 2024-03-01-preview and 2024-04-01-preview API specification

• Breaking Change: Enhancements parameters removed. This change impacts the gpt-4 Version: vision-preview model.
• timestamp_granularities parameter added.
• audioWord object added.
• Additional TTS response_formats: wav & pcm.

Known issues

• The 2025-04-01-preview Azure OpenAI spec uses OpenAPI 3.1. It's a known issue that this version isn't fully supported by Azure API Management.

Next steps

• The Azure OpenAI Starter Kit
• Azure OpenAI To Responses
• Supported programming languages for the v1 API
• Foundry Models sold by Azure
• Working with Azure OpenAI models
• Azure OpenAI quotas and limits
• v1 OpenAPI 3.0 spec