Azure OpenAI in Microsoft Foundry Models v1 API - Microsoft Foundry (original) (raw)

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

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:

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:

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

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:

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://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))

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.

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))

v1 API support

API version changelog

The following sections summarize changes between API versions.

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

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

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

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

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

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

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

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

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

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

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

Known issues

Next steps