Edit

Share via

Azure OpenAI supported programming languages

Source code | Package (NuGet)

Azure OpenAI API version support

  • v1 Generally Available (GA) API now allows access to both GA and Preview operations. To learn more, see the API version lifecycle guide.

Installation

dotnet add package OpenAI

Authentication

A secure, keyless authentication approach is to use Microsoft Entra ID (formerly Azure Active Directory) via the Azure Identity library. To use the library:

dotnet add package Azure.Identity

Use the desired credential type from the library. For example, DefaultAzureCredential:

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: "gpt-4.1-nano",
    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 bitter lesson.'");

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

For more information about Azure OpenAI keyless authentication, see the "Get started with the Azure OpenAI security building block" QuickStart article.

Chat

Example of chat completions request to a reasoning model.

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

#pragma warning disable OPENAI001 //currently required for token based authentication

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

ChatClient client = new(
    model: "o4-mini",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {

        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
    }
);

ChatCompletionOptions options = new ChatCompletionOptions
{
    ReasoningEffortLevel = ChatReasoningEffortLevel.Low,
    MaxOutputTokenCount = 100000
};

ChatCompletion completion = client.CompleteChat(
         new DeveloperChatMessage("You are a helpful assistant"),
         new UserChatMessage("Tell me about the bitter lesson")
    );

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

Embeddings

using OpenAI;
using OpenAI.Embeddings;
using System.ClientModel;

string apiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
    ?? throw new InvalidOperationException("AZURE_OPENAI_API_KEY environment variable is not set");

EmbeddingClient client = new(
    "text-embedding-3-large",
    credential: new ApiKeyCredential(apiKey),
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
    }
);

string input = "This is a test";

OpenAIEmbedding embedding = client.GenerateEmbedding(input);
ReadOnlyMemory<float> vector = embedding.ToFloats();
Console.WriteLine($"Embeddings: [{string.Join(", ", vector.ToArray())}]");

Responses API

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

#pragma warning disable OPENAI001 //currently required for token based authentication

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

#pragma warning disable OPENAI001

OpenAIResponseClient client = new(
    model: "o4-mini",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
    }
);

OpenAIResponse response = await client.CreateResponseAsync(
    userInputText: "What's the optimal strategy to win at poker?",
    new ResponseCreationOptions()
    {
        ReasoningOptions = new ResponseReasoningOptions()
        {
            ReasoningEffortLevel = ResponseReasoningEffortLevel.High,
        },
    });

Console.WriteLine(response.GetOutputText());

Streaming

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

#pragma warning disable OPENAI001 //currently required for token based authentication

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

#pragma warning disable OPENAI001

OpenAIResponseClient client = new(
    model: "o4-mini",
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
    }
);


await foreach (StreamingResponseUpdate update
    in client.CreateResponseStreamingAsync(
        userInputText: "What's the optimal strategy to win at poker?",
        new ResponseCreationOptions()
        {
            ReasoningOptions = new ResponseReasoningOptions()
            {
                ReasoningEffortLevel = ResponseReasoningEffortLevel.High,
            },
        }))
{
    if (update is StreamingResponseOutputItemAddedUpdate itemUpdate
        && itemUpdate.Item is ReasoningResponseItem reasoningItem)
    {
        Console.WriteLine($"[Reasoning] ({reasoningItem.Status})");
    }
    else if (update is StreamingResponseOutputTextDeltaUpdate delta)
    {
        Console.Write(delta.Delta);
    }
}

Error handling

Error codes

Status Code Error Type
400 Bad Request Error
401 Authentication Error
403 Permission Denied Error
404 Not Found Error
422 Unprocessable Entity Error
429 Rate Limit Error
500 Internal Server Error
503 Service Unavailable
504 Gateway Timeout

Retries

The client classes will automatically retry the following errors up to three more times using exponential backoff:

  • 408 Request Timeout
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Source code | Package (pkg.go.dev) | REST API reference documentation | Package reference documentation

Azure OpenAI API version support

  • v1 Generally Available (GA) API now allows access to both GA and Preview operations. To learn more, see the API version lifecycle guide.

Installation

Install the openai and azidentity modules with go get:

go get -u 'github.com/openai/openai-go@v2.1.1'

# optional
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Authentication

The azidentity module is used for Microsoft Entra ID authentication with Azure OpenAI.

package main

import (
	"context"
	"fmt"

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

func main() {
	// Create an Azure credential
	tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		panic(fmt.Sprintf("Failed to create credential: %v", 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: "o4-mini", // Use your deployed model name on Azure
	})
	if err != nil {
		panic(err.Error())
	}

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

For more information about Azure OpenAI keyless authentication, see Use Azure OpenAI without keys.

Embeddings

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go/v2"
	"github.com/openai/openai-go/v2/option"
)

func main() {
	// Get API key from environment variable
	apiKey := os.Getenv("AZURE_OPENAI_API_KEY")
	if apiKey == "" {
		panic("AZURE_OPENAI_API_KEY environment variable is not set")
	}

	// Create a client with Azure OpenAI endpoint and API key
	client := openai.NewClient(
		option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
		option.WithAPIKey(apiKey),
	)

	ctx := context.Background()
	text := "The attention mechanism revolutionized natural language processing"

	// Make an embedding request
	embedding, err := client.Embeddings.New(ctx, openai.EmbeddingNewParams{
		Input: openai.EmbeddingNewParamsInputUnion{OfString: openai.String(text)},
		Model: "text-embedding-3-small", // Use your deployed model name on Azure
	})
	if err != nil {
		panic(err.Error())
	}

	// Print embedding information
	fmt.Printf("Model: %s\n", embedding.Model)
	fmt.Printf("Number of embeddings: %d\n", len(embedding.Data))
	fmt.Printf("Embedding dimensions: %d\n", len(embedding.Data[0].Embedding))
	fmt.Printf("Usage - Prompt tokens: %d, Total tokens: %d\n", embedding.Usage.PromptTokens, embedding.Usage.TotalTokens)
	
	// Print first few values of the embedding vector
	fmt.Printf("First 10 embedding values: %v\n", embedding.Data[0].Embedding[:10])
}

Responses

package main

import (
	"context"

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

func main() {
	// Create Azure token credential
	tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		panic(err)
	}

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

	ctx := context.Background()
	question := "Tell me about the attention is all you need paper"

	resp, err := client.Responses.New(ctx, responses.ResponseNewParams{
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String(question)},
		Model: "o4-mini",
	})

	if err != nil {
		panic(err)
	}

	println(resp.OutputText())
}

Source code | Artifact (Maven) | API reference documentation | Package reference documentation Samples

Azure OpenAI API version support

Unlike the Azure OpenAI client libraries for Python and JavaScript, to ensure compatibility the Azure OpenAI Java package is limited to targeting a specific subset of the Azure OpenAI API versions. Generally each Azure OpenAI Java package unlocks access to newer Azure OpenAI API release features. Having access to the latest API versions impacts feature availability.

Version selection is controlled by the OpenAIServiceVersion enum.

The latest Azure OpenAI preview API supported is:

-2025-01-01-preview

The latest stable (GA) release supported is:

-2024-06-01

Installation

Package details

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-openai</artifactId>
    <version>1.0.0-beta.16</version>
</dependency>

Authentication

In order to interact with the Azure OpenAI in Azure AI Foundry Models you'll need to create an instance of client class, OpenAIAsyncClient or OpenAIClient by using OpenAIClientBuilder. To configure a client for use with Azure OpenAI, provide a valid endpoint URI to an Azure OpenAI resource along with a corresponding key credential, token credential, or Azure Identity credential that's authorized to use the Azure OpenAI resource.

Authentication with Microsoft Entra ID requires some initial setup:

Add the Azure Identity package:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

After setup, you can choose which type of credential from azure.identity to use. As an example, DefaultAzureCredential can be used to authenticate the client: Set the values of the client ID, tenant ID, and client secret of the Microsoft Entra ID application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Authorization is easiest using DefaultAzureCredential. It finds the best credential to use in its running environment.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = new OpenAIClientBuilder()
    .credential(defaultCredential)
    .endpoint("{endpoint}")
    .buildClient();

For more information about Azure OpenAI keyless authentication, see Use Azure OpenAI without keys.

Audio

client.getAudioTranscription

String fileName = "{your-file-name}";
Path filePath = Paths.get("{your-file-path}" + fileName);

byte[] file = BinaryData.fromFile(filePath).toBytes();
AudioTranscriptionOptions transcriptionOptions = new AudioTranscriptionOptions(file)
    .setResponseFormat(AudioTranscriptionFormat.JSON);

AudioTranscription transcription = client.getAudioTranscription("{deploymentOrModelName}", fileName, transcriptionOptions);

System.out.println("Transcription: " + transcription.getText());

client.generateSpeechFromText

Text to speech (TTS)

String deploymentOrModelId = "{azure-open-ai-deployment-model-id}";
SpeechGenerationOptions options = new SpeechGenerationOptions(
        "Today is a wonderful day to build something people love!",
        SpeechVoice.ALLOY);
BinaryData speech = client.generateSpeechFromText(deploymentOrModelId, options);
// Checkout your generated speech in the file system.
Path path = Paths.get("{your-local-file-path}/speech.wav");
Files.write(path, speech.toBytes());

Chat

client.getChatCompletions

List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatRequestUserMessage("Can you help me?"));
chatMessages.add(new ChatRequestAssistantMessage("Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatRequestUserMessage("What's the best way to train a parrot?"));

ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}",
    new ChatCompletionsOptions(chatMessages));

System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
    ChatResponseMessage message = choice.getMessage();
    System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
    System.out.println("Message:");
    System.out.println(message.getContent());
}

Streaming

List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatRequestUserMessage("Can you help me?"));
chatMessages.add(new ChatRequestAssistantMessage("Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatRequestUserMessage("What's the best way to train a parrot?"));

ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}",
    new ChatCompletionsOptions(chatMessages));

System.out.printf("Model ID=%s is created at %s.%n", chatCompletions.getId(), chatCompletions.getCreatedAt());
for (ChatChoice choice : chatCompletions.getChoices()) {
    ChatResponseMessage message = choice.getMessage();
    System.out.printf("Index: %d, Chat Role: %s.%n", choice.getIndex(), message.getRole());
    System.out.println("Message:");
    System.out.println(message.getContent());
}

Chat completions with images

List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant that describes images"));
chatMessages.add(new ChatRequestUserMessage(Arrays.asList(
        new ChatMessageTextContentItem("Please describe this image"),
        new ChatMessageImageContentItem(
                new ChatMessageImageUrl("https://raw.githubusercontent.com/MicrosoftDocs/azure-ai-docs/main/articles/ai-services/openai/media/how-to/generated-seattle.png"))
)));

ChatCompletionsOptions chatCompletionsOptions = new ChatCompletionsOptions(chatMessages);
ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}", chatCompletionsOptions);

System.out.println("Chat completion: " + chatCompletions.getChoices().get(0).getMessage().getContent());

Embeddings

client.getEmbeddings

EmbeddingsOptions embeddingsOptions = new EmbeddingsOptions(
    Arrays.asList("Your text string goes here"));

Embeddings embeddings = client.getEmbeddings("{deploymentOrModelName}", embeddingsOptions);

for (EmbeddingItem item : embeddings.getData()) {
    System.out.printf("Index: %d.%n", item.getPromptIndex());
    for (Float embedding : item.getEmbedding()) {
        System.out.printf("%f;", embedding);
    }
}

Image generation

ImageGenerationOptions imageGenerationOptions = new ImageGenerationOptions(
    "A drawing of the Seattle skyline in the style of Van Gogh");
ImageGenerations images = client.getImageGenerations("{deploymentOrModelName}", imageGenerationOptions);

for (ImageGenerationData imageGenerationData : images.getData()) {
    System.out.printf(
        "Image ___location URL that provides temporary access to download the generated image is %s.%n",
        imageGenerationData.getUrl());
}

Handling errors

Enable client logging

To troubleshoot issues with Azure OpenAI library, it's important to first enable logging to monitor the behavior of the application. The errors and warnings in the logs generally provide useful insights into what went wrong and sometimes include corrective actions to fix issues. The Azure client libraries for Java have two logging options:

  • A built-in logging framework.
  • Support for logging using the SLF4J interface.

Refer to the instructions in this reference document on how to [configure logging in Azure SDK for Java][logging_overview].

Enable HTTP request/response logging

Reviewing the HTTP request sent or response received over the wire to/from the Azure OpenAI can be useful in troubleshooting issues. To enable logging the HTTP request and response payload, the [OpenAIClient][openai_client] can be configured as shown below. If there's no SLF4J's Logger on the class path, set an environment variable [AZURE_LOG_LEVEL][azure_log_level] in your machine to enable logging.

OpenAIClient openAIClient = new OpenAIClientBuilder()
        .endpoint("{endpoint}")
        .credential(new AzureKeyCredential("{key}"))
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();
// or
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
OpenAIClient configurationClientAad = new OpenAIClientBuilder()
        .credential(credential)
        .endpoint("{endpoint}")
        .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
        .buildClient();

Alternatively, you can configure logging HTTP requests and responses for your entire application by setting the following environment variable. Note that this change will enable logging for every Azure client that supports logging HTTP request/response.

Environment variable name: AZURE_HTTP_LOG_DETAIL_LEVEL

Value Logging level
none HTTP request/response logging is disabled
basic Logs only URLs, HTTP methods, and time to finish the request.
headers Logs everything in BASIC, plus all the request and response headers.
body Logs everything in BASIC, plus all the request and response body.
body_and_headers Logs everything in HEADERS and BODY.

Note

When logging the body of request and response, ensure that they don't contain confidential information. When logging headers, the client library has a default set of headers that are considered safe to log but this set can be updated by updating the log options in the builder as shown below.

clientBuilder.httpLogOptions(new HttpLogOptions().addAllowedHeaderName("safe-to-log-header-name"))

Troubleshooting exceptions

Azure OpenAI methods throw a[HttpResponseException or its subclass on failure. The HttpResponseException thrown by the OpenAI client library includes detailed response error object that provides specific useful insights into what went wrong and includes corrective actions to fix common issues. This error information can be found inside the message property of the HttpResponseException object.

Here's the example of how to catch it with synchronous client

List<ChatRequestMessage> chatMessages = new ArrayList<>();
chatMessages.add(new ChatRequestSystemMessage("You are a helpful assistant. You will talk like a pirate."));
chatMessages.add(new ChatRequestUserMessage("Can you help me?"));
chatMessages.add(new ChatRequestAssistantMessage("Of course, me hearty! What can I do for ye?"));
chatMessages.add(new ChatRequestUserMessage("What's the best way to train a parrot?"));

try {
    ChatCompletions chatCompletions = client.getChatCompletions("{deploymentOrModelName}",
            new ChatCompletionsOptions(chatMessages));
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
    // Do something with the exception
}

With async clients, you can catch and handle exceptions in the error callbacks:

asyncClient.getChatCompletions("{deploymentOrModelName}", new ChatCompletionsOptions(chatMessages))
        .doOnSuccess(ignored -> System.out.println("Success!"))
        .doOnError(
                error -> error instanceof ResourceNotFoundException,
                error -> System.out.println("Exception: 'getChatCompletions' could not be performed."));

Authentication errors

Azure OpenAI supports Microsoft Entra ID authentication. OpenAIClientBuilder has method to set the credential. To provide a valid credential, you can use azure-identity dependency.

Source code | Package (npm) | Reference |

Azure OpenAI API version support

Feature availability in Azure OpenAI is dependent on what version of the REST API you target. For the newest features, target the latest preview API.

Latest GA API Latest Preview API
2024-10-21 2025-03-01-preview

Installation

npm install openai

Authentication

There are several ways to authenticate with the Azure OpenAI using Microsoft Entra ID tokens. The default way is to use the DefaultAzureCredential class from the @azure/identity package.

import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();

This object is then passed as part of the AzureClientOptions object to the AzureOpenAI and AssistantsClient client constructors.

In order to authenticate the AzureOpenAI client, however, we need to use the getBearerTokenProvider function from the @azure/identity package. This function creates a token provider that AzureOpenAI uses internally to obtain tokens for each request. The token provider is created as follows:

import { AzureOpenAI } from 'openai';
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
const credential = new DefaultAzureCredential();
const endpoint = "https://your-azure-openai-resource.com";
const apiVersion = "2024-10-21"
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(credential, scope);
const deployment = "gpt-35-turbo";

const client = new AzureOpenAI({ 
    endpoint, 
    apiVersion,
    deployment,
    azureADTokenProvider
});

For more information about Azure OpenAI keyless authentication, see the "Get started with the Azure OpenAI security building block" QuickStart article.

Configuration

The AzureClientOptions object extends the OpenAI ClientOptions object. This Azure-specific client object is used to configure the connection and behavior of the Azure OpenAI client. It includes properties for specifying the properties unique to Azure.

Property Details
apiVersion: string Specifies the API version to use.
azureADTokenProvider: (() => Promise<string>) A function that returns an access token for Microsoft Entra (formerly known as Azure Active Directory), invoked on every request.
deployment: string A model deployment. If provided, sets the base client URL to include /deployments/{deployment}. Non-deployment endpoints can't be used (not supported with Assistants APIs).
endpoint: string Your Azure OpenAI endpoint with the following format: https://RESOURCE-NAME.azure.openai.com/.

Audio

Transcription

import { createReadStream } from "fs";

const result = await client.audio.transcriptions.create({
  model: '',
  file: createReadStream(audioFilePath),
});

Chat

chat.completions.create

const result = await client.chat.completions.create({ messages, model: '', max_tokens: 100 });

Streaming

const stream = await client.chat.completions.create({ model: '', messages, max_tokens: 100, stream: true });

Embeddings

const embeddings = await client.embeddings.create({ input, model: '' });

Image generation

  const results = await client.images.generate({ prompt, model: '', n, size });

Error handling

Error codes

Status Code Error Type
400 Bad Request Error
401 Authentication Error
403 Permission Denied Error
404 Not Found Error
422 Unprocessable Entity Error
429 Rate Limit Error
500 Internal Server Error
503 Service Unavailable
504 Gateway Timeout

Retries

The following errors are automatically retired twice by default with a brief exponential backoff:

  • Connection Errors
  • 408 Request Timeout
  • 429 Rate Limit
  • >=500 Internal Errors

Use maxRetries to set/disable the retry behavior:

// Configure the default for all requests:
const client = new AzureOpenAI({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.chat.completions.create({ messages: [{ role: 'user', content: 'How can I get the name of the current day in Node.js?' }], model: '' }, {
  maxRetries: 5,
});

Library source code | Package (PyPi) | Reference |

Note

This library is maintained by OpenAI. Refer to the release history to track the latest updates to the library.

Azure OpenAI API version support

  • v1 Generally Available (GA) API now allows access to both GA and Preview operations. To learn more, see the API version lifecycle guide.

Installation

pip install openai

For the latest version:

pip install openai --upgrade

Authentication

Important

Use API keys with caution. Don't include the API key directly in your code, and never post it publicly. If you use an API key, store it securely in Azure Key Vault. For more information about using API keys securely in your apps, see API keys with Azure Key Vault.

For more information about AI services security, see Authenticate requests to Azure AI services.

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

Chat

chat.completions.create()

# from openai import OpenAI
# client = OpenAI()

completion = client.chat.completions.create(
  model="gpt-4o", # Replace with your model deployment name.
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "When was Microsoft founded?"}
  ]
)

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

chat.completions.create() - streaming

# from openai import OpenAI
# client = OpenAI()

completion = client.chat.completions.create(
  model="gpt-4o", # Replace with your model deployment name.
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "When was Microsoft founded?"}
  ],
  stream=True
)

for chunk in completion:
    if chunk.choices and chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end='',)

chat.completions.create() - image input

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://raw.githubusercontent.com/MicrosoftDocs/azure-ai-docs/main/articles/ai-foundry/openai/media/how-to/generated-seattle.png",
                    }
                },
            ],
        }
    ],
    max_tokens=300,
)

print(completion.model_dump_json(indent=2))

Embeddings

embeddings.create()

# from openai import OpenAI
# client = OpenAI()

embedding = client.embeddings.create(
  model="text-embedding-3-large", # Replace with your model deployment name
  input="Attenion is all you need",
  encoding_format="float" 
)

print(embedding)

Fine-tuning

Fine-tuning with Python how-to article

Responses API

See the Responses API documentation.

Error handling

# from openai import OpenAI
# client = OpenAI()

import openai

try:
    client.fine_tuning.jobs.create(
        model="gpt-4o",
        training_file="file-test",
    )
except openai.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx.
except openai.RateLimitError as e:
    print("A 429 status code was received; we should back off a bit.")
except openai.APIStatusError as e:
    print("Another non-200-range status code was received")
    print(e.status_code)
    print(e.response)

Error codes

Status Code Error Type
400 BadRequestError
401 AuthenticationError
403 PermissionDeniedError
404 NotFoundError
422 UnprocessableEntityError
429 RateLimitError
>=500 InternalServerError
N/A APIConnectionError

Request IDs

To retrieve the ID of your request you can use the _request_id property which corresponds to the x-request-id response header.

print(completion._request_id) 
print(legacy_completion._request_id)

Retries

The following errors are automatically retired twice by default with a brief exponential backoff:

  • Connection Errors
  • 408 Request Timeout
  • 429 Rate Limit
  • >=500 Internal Errors

Use max_retries to set/disable the retry behavior:

# For all requests

from openai import OpenAI
client = OpenAI(
      max_retries=0
)

# max retires for specific requests

client.with_options(max_retries=5).chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "When was Microsoft founded?",
        }
    ],
    model="gpt-4o",
)

Next steps