Edit

Share via

How to switch between OpenAI and Azure OpenAI endpoints

This article shows you how to switch to the new unified OpenAI v1 chat completion endpoint. It covers the common changes and differences when you work with OpenAI and Azure OpenAI.

While OpenAI and Azure OpenAI rely on a common Python client library, there were small changes you needed to make to your code in order to swap back and forth between the endpoints. The new unified OpenAI v1 chat completion endpoint eliminates the need for separate Azure-specific code paths.

Authentication

We recommend keyless authentication using Microsoft Entra ID. If that's not possible, use an API key and store it in Azure Key Vault. You can use an environment variable for testing outside of your Azure environments.

API key authentication

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
)

Microsoft Entra authentication

Microsoft Entra authentication is only supported with Azure OpenAI resources. Complete the following steps:

  1. Install the Azure Identity client library:

    pip install azure-identity

  2. Configure the OpenAI client object as follows:

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

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

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

    Tip

    DefaultAzureCredential can be optimized for the environment in which your app runs. For more information, see How to customize DefaultAzureCredential.

  3. Assign the appropriate Azure role-based access control (RBAC) permissions. For more information, see Azure role-based access control (RBAC).

    When running in Azure, assign roles to the managed identity used by the Azure host resource. When running in the local development environment, assign roles to the user running the app.

using OpenAI;
using System;
using System.ClientModel;

string apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY");
OpenAIClient client = new(new ApiKeyCredential(apiKey));

Microsoft Entra authentication

Microsoft Entra authentication is only supported with Azure OpenAI resources. Complete the following steps:

  1. Install the Azure Identity client library:

    dotnet add package Azure.Identity

  2. Configure the OpenAIClient object as follows:

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

// code omitted for brevity

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

OpenAIClientOptions clientOptions = new()
{
    Endpoint = new Uri($"{resourceEndpoint}/openai/v1/")
};

OpenAIClient client = new(tokenPolicy, clientOptions);

    Tip

    DefaultAzureCredential can be optimized for the environment in which your app runs. For more information, see How to customize DefaultAzureCredential.

  3. Assign the appropriate Azure role-based access control (RBAC) permissions. For more information, see Azure role-based access control (RBAC).

    When running in Azure, assign roles to the managed identity used by the Azure host resource. When running in the local development environment, assign roles to the user running the app.

import { OpenAI } from "openai";
import "dotenv/config";

const apiKey = process.env["OPENAI_API_KEY"];

if (!endpoint) {
  throw new Error("Please set the OPENAI_API_KEY environment variable.");
}

const client = new OpenAI({ apiKey });

Microsoft Entra authentication

Microsoft Entra authentication is only supported with Azure OpenAI resources. Complete the following steps:

  1. Install the Azure Identity client library:

    npm install @azure/identity

  2. Configure the OpenAI client object as follows:

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

const endpoint = process.env["AZURE_OPENAI_ENDPOINT"];

if (!endpoint) {
  throw new Error("Please set the AZURE_OPENAI_ENDPOINT environment variable.");
}

const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint + "/openai/v1", apiKey: azureADTokenProvider });

    Tip

    DefaultAzureCredential can be optimized for the environment in which your app runs. For more information, see How to customize DefaultAzureCredential.

  3. Assign the appropriate Azure role-based access control (RBAC) permissions. For more information, see Azure role-based access control (RBAC).

    When running in Azure, assign roles to the managed identity used by the Azure host resource. When running in the local development environment, assign roles to the user running the app.

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

public class OpenAISample {

    public static void main(String[] args) {
        OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .build();
    }
}

Microsoft Entra authentication

Microsoft Entra authentication is only supported with Azure OpenAI resources. Complete the following steps:

  1. Include the azure-identity dependency in your project.

  2. Configure the OpenAIClient object as follows:

    import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;

import java.util.function.Supplier;

public class AzureOpenAISample {

    public static void main(String[] args) {
        DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
        Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
                tokenCredential, "https://cognitiveservices.azure.com/.default");
        OpenAIClient azureOpenAIClient = OpenAIOkHttpClient.builder()
                .fromEnv()
                // Set the Azure Entra ID
                .credential(BearerTokenCredential.create(bearerTokenSupplier))
                .build();
    }
}

    Tip

    DefaultAzureCredential can be optimized for the environment in which your app runs. For more information, see How to customize DefaultAzureCredential.

  3. Assign the appropriate Azure role-based access control (RBAC) permissions. For more information, see Azure role-based access control (RBAC).

    When running in Azure, assign roles to the managed identity used by the Azure host resource. When running in the local development environment, assign roles to the user running the app.

// import (
//    "github.com/openai/openai-go/v3"
//    "github.com/openai/openai-go/v3/option"
// )

client := openai.NewClient(
    option.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
)

Microsoft Entra authentication

Microsoft Entra authentication is only supported with Azure OpenAI resources. Complete the following steps:

  1. Include the azure-identity dependency in your project.

  2. Configure the OpenAIClient object as follows:

    // import (
//    "github.com/openai/openai-go/v3"
//    "github.com/openai/openai-go/v3/azure"
//    "github.com/openai/openai-go/v3/option"
// )

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

    Tip

    DefaultAzureCredential can be optimized for the environment in which your app runs. For more information, see How to customize DefaultAzureCredential.

  3. Assign the appropriate Azure role-based access control (RBAC) permissions. For more information, see Azure role-based access control (RBAC).

    When running in Azure, assign roles to the managed identity used by the Azure host resource. When running in the local development environment, assign roles to the user running the app.

Specify the model

OpenAI uses the model keyword argument to specify what model to use. Azure OpenAI has the concept of unique model deployments. When you use Azure OpenAI, model should refer to the underlying deployment name you chose when you deployed the model.

Important

Azure OpenAI and OpenAI handle model names differently in API calls. OpenAI only needs the model name. Azure OpenAI always needs the deployment name, even when you use the model parameter. You must use the deployment name instead of the model name when you call Azure OpenAI APIs. Our documentation often shows deployment names that match model names to show which model works with each API endpoint. Choose any naming convention for deployment names that works best for you.

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

chat_completion = client.chat.completions.create(
    model="gpt-4o", 
    messages="<messages>"
)

embedding = client.embeddings.create(
    model="text-embedding-3-large", 
    input="<input>"
)

OpenAI uses the model parameter to specify what model to use. Azure OpenAI has the concept of unique model deployments. When you use Azure OpenAI, model should refer to the underlying deployment name you chose when you deployed the model.

Important

Azure OpenAI and OpenAI handle model names differently in API calls. OpenAI only needs the model name. Azure OpenAI always needs the deployment name, even when you use the model parameter. You must use the deployment name instead of the model name when you call Azure OpenAI APIs. Our documentation often shows deployment names that match model names to show which model works with each API endpoint. Choose any naming convention for deployment names that works best for you.

string modelName = "gpt-4.1-nano";
OpenAIResponseClient response = client.GetOpenAIResponseClient(modelName);

modelName = "gpt-4o";
ChatClient chatCompletion = client.GetChatClient(modelName);

modelName = "text-embedding-3-large";
EmbeddingClient embedding = client.GetEmbeddingClient(modelName);

OpenAI uses the model keyword argument to specify what model to use. Azure OpenAI has the concept of unique model deployments. When you use Azure OpenAI, model should refer to the underlying deployment name you chose when you deployed the model.

Important

Azure OpenAI and OpenAI handle model names differently in API calls. OpenAI only needs the model name. Azure OpenAI always needs the deployment name, even when you use the model parameter. You must use the deployment name instead of the model name when you call Azure OpenAI APIs. Our documentation often shows deployment names that match model names to show which model works with each API endpoint. Choose any naming convention for deployment names that works best for you.

const response = await client.responses.create({
  model: "gpt-4.1-nano",
  input: "This is a test",
});

const chatCompletions = await client.chat.completions.create({
  model: "gpt-4o",
  messages: ["<messages>"],
});

const embeddings = await client.embeddings.create({
  model: "text-embedding-3-large",
  input: "<input>",
});

OpenAI uses the model keyword argument to specify what model to use. Azure OpenAI has the concept of unique model deployments. When you use Azure OpenAI, model should refer to the underlying deployment name you chose when you deployed the model.

Important

Azure OpenAI and OpenAI handle model names differently in API calls. OpenAI only needs the model name. Azure OpenAI always needs the deployment name, even when you use the model parameter. You must use the deployment name instead of the model name when you call Azure OpenAI APIs. Our documentation often shows deployment names that match model names to show which model works with each API endpoint. Choose any naming convention for deployment names that works best for you.

ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
        .input("This is a test")
        .model(ChatModel.GPT_4_1_NANO)
        .build();

Response response = client.responses().create(responseCreateParams);

ChatCompletionCreateParams chatCompletionCreateParams = ChatCompletionCreateParams.builder()
        .model(ChatModel.GPT_4O)
        .addUserMessage("<message>")
        .build();

ChatCompletion chatCompletion = client.chat().completions().create(chatCompletionCreateParams);

EmbeddingCreateParams embeddingCreateParams = EmbeddingCreateParams.builder()
        .input("<input>")
        .model(EmbeddingModel.TEXT_EMBEDDING_3_LARGE)
        .build();

CreateEmbeddingResponse createEmbeddingResponse = client.embeddings().create(embeddingCreateParams);

OpenAI uses the Model keyword argument to specify what model to use. Azure OpenAI has the concept of unique model deployments. When you use Azure OpenAI, Model should refer to the underlying deployment name you chose when you deployed the model.

Important

Azure OpenAI and OpenAI handle model names differently in API calls. OpenAI only needs the model name. Azure OpenAI always needs the deployment name, even when you use the model parameter. You must use the deployment name instead of the model name when you call Azure OpenAI APIs. Our documentation often shows deployment names that match model names to show which model works with each API endpoint. Choose any naming convention for deployment names that works best for you.

resp, err := client.Responses.New(context.TODO(), responses.ResponseNewParams{
    Model: "gpt-4.1-nano", 
    Input: responses.ResponseNewParamsInputUnion{
        OfString: openai.String("This is a test."),
    },
})

resp, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
    Model: "gpt-4o", 
    Messages: []openai.ChatCompletionMessageParamUnion{
        // messages
    },
})

resp, err := client.Embeddings.New(context.TODO(), openai.EmbeddingNewParams{
    Model: "text-embedding-3-large", 
    Input: openai.EmbeddingNewParamsInputUnion{
        OfString: openai.String("<input>"),
    },
})

Azure OpenAI embeddings multiple input support

OpenAI and Azure OpenAI currently support input arrays up to 2,048 input items for text-embedding-ada-002. Both require the max input token limit per API request to remain under 8,191 for this model.

inputs = ["A", "B", "C"] 

embedding = client.embeddings.create(
    input=inputs,
    model="text-embedding-3-large"
)

string[] inputs = [ "A", "B", "C" ];

EmbeddingClient embedding = client.GetEmbeddingClient(
    model: "text-embedding-3-large"
).GenerateEmbedding(
    input: inputs
);

const embeddings = await client.embeddings.create({
    model: "text-embedding-3-large",
    inputs: ["A", "B", "C"],
})

EmbeddingCreateParams embeddingCreateParams = EmbeddingCreateParams.builder()
        .inputOfArrayOfStrings(List.of("A", "B", "C"))
        .model(EmbeddingModel.TEXT_EMBEDDING_3_LARGE)
        .build();

CreateEmbeddingResponse createEmbeddingResponse = client.embeddings().create(embeddingCreateParams);

resp, err := client.Embeddings.New(context.TODO(), openai.EmbeddingNewParams{
    Model: "text-embedding-3-large",
    Input: openai.EmbeddingNewParamsInputUnion{
        OfArrayOfStrings: []string{"A", "B", "C"},
    },
})