Azure OpenAI in Microsoft Foundry Models v1 API

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.

Note

New API response objects might be added to the API response at any time. We recommend you only parse the response objects you require.

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 will be controlled by passing feature specific preview headers allowing you to opt in to the features you want, without having to swap API versions. Alternatively, some features will indicate preview status through their API path and don't require an additional header.

Examples:

• /openai/v1/evals is in preview and requires passing an "aoai-evals":"preview" header.
• /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().
• base_url passes the Azure OpenAI endpoint and /openai/v1 is appended 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:

Important

Handling automatic token refresh was previously handled through use of the AzureOpenAI() client. The v1 API removes this dependency, by adding automatic token refresh support to the OpenAI() client.

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.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)) 

• base_url passes the Azure OpenAI endpoint and /openai/v1 is appended to the endpoint address.
• api_key parameter is set to token_provider, enabling 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://cognitiveservices.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://cognitiveservices.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://cognitiveservices.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 will accept both https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ and https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ formats.

Note

Responses API also works with Foundry Models sold directly by Azure, such as Microsoft AI, DeepSeek, and Grok models. To learn how to use the Responses API with these models, see How to generate text responses with Microsoft Foundry Models.

Python

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.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://cognitiveservices.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 tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://cognitiveservices.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

const messages = [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Tell me about the attention is all you need paper' }
];

// Make the API request with top-level await
const result = await client.chat.completions.create({ 
    messages, 
    model: 'MAI-DS-R1', // model deployment name
    max_tokens: 100 
});

// Print the full response
console.log('Full response:', result);

// Print just the message content from the response
console.log('Response content:', result.choices[0].message.content);

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

Status

Generally Available features are supported for use in production.

API Path	Status
/openai/v1/chat/completions	Generally Available
/openai/v1/embeddings	Generally Available
/openai/v1/evals	Preview
/openai/v1/files	Generally Available
/openai/v1/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints/{fine_tuning_checkpoint_id}/copy	Preview
/openai/v1/fine_tuning/alpha/graders/	Preview
/openai/v1/fine_tuning/	Generally Available
/openai/v1/models	Generally Available
/openai/v1/responses	Generally Available
/openai/v1/vector_stores	Generally Available

Preview headers

API Path	Header
/openai/v1/evals	"aoai-evals":"preview"
/openai/v1/fine_tuning/jobs/{fine_tuning_job_id}/checkpoints/{fine_tuning_checkpoint_id}/copy	"aoai-copy-ft-checkpoints" : "preview"

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 impacts the gpt-4 Version: vision-preview model.
• timestamp_granularities parameter added.
• audioWord object added.
• Additional TTS response_formats: wav & pcm.

Troubleshooting

Issue	Cause	Solution
404 Not Found when calling the v1 API	Incorrect base_url format	Verify the URL ends with /openai/v1/. Both https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ and https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ are valid.
401 Unauthorized with Entra ID	Missing or incorrect role assignment	Assign the Cognitive Services OpenAI User role to your identity. Role assignments can take up to 5 minutes to propagate.
AzureOpenAI() client doesn't work with v1	v1 API uses the OpenAI() client	Replace AzureOpenAI() with OpenAI() and set base_url to your Azure endpoint with /openai/v1/ appended.
api-version parameter rejected	v1 API doesn't use api-version	Remove any api-version query parameters from your requests. The v1 API doesn't require or accept them.
Preview features not available	Missing preview header	For preview APIs like /openai/v1/evals, pass the required preview header (for example, "aoai-evals":"preview"). See Preview headers.

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

• Supported programming languages for the v1 API
• Foundry Models sold directly by Azure
• Working with Azure OpenAI models
• Azure OpenAI quotas and limits
• v1 OpenAPI 3.0 spec