Azure OpenAI supported programming languages
The Azure OpenAI client library for .NET is a companion to the official OpenAI client library for .NET. The Azure OpenAI library configures a client for use with Azure OpenAI and provides additional strongly typed extension support for request and response models specific to Azure OpenAI scenarios.
Stable release:
Source code | Package (NuGet) | Package reference documentation API reference documentation | Samples
Preview release:
The preview release will have access to the latest features.
Source code | Package (NuGet) | API reference documentation | Package reference documentation Samples
Azure OpenAI API version support
Unlike the Azure OpenAI client libraries for Python and JavaScript, the Azure OpenAI .NET package is limited to targeting a specific subset of the Azure OpenAI API versions. Generally each Azure OpenAI .NET package will unlock access to newer Azure OpenAI API release features. Having access to the latest API versions impacts feature availability.
Version selection is controlled by the AzureOpenAIClientOptions.ServiceVersion enum.
The stable release currently targets:
2024-06-01
The preview release can currently target:
2024-06-012024-08-01-preview2024-09-01-preview2024-10-01-preview
Installation
dotnet add package Azure.AI.OpenAI --prerelease
The Azure.AI.OpenAI package builds on the official OpenAI package, which is included as a dependency.
Authentication
To interact with Azure OpenAI or OpenAI, create an instance of AzureOpenAIClient with one of the following approaches:
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:
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-mini-deployment");
Audio
AzureOpenAIClient.GetAudioClient
Transcription
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
AudioClient client = azureClient.GetAudioClient("whisper");
string audioFilePath = Path.Combine("Assets", "speech.mp3");
AudioTranscriptionOptions options = new()
{
ResponseFormat = AudioTranscriptionFormat.Verbose,
TimestampGranularities = AudioTimestampGranularities.Word | AudioTimestampGranularities.Segment,
};
AudioTranscription transcription = client.TranscribeAudio(audioFilePath, options);
Console.WriteLine("Transcription:");
Console.WriteLine($"{transcription.Text}");
Console.WriteLine();
Console.WriteLine($"Words:");
foreach (TranscribedWord word in transcription.Words)
{
Console.WriteLine($" {word.Word,15} : {word.StartTime.TotalMilliseconds,5:0} - {word.EndTime.TotalMilliseconds,5:0}");
}
Console.WriteLine();
Console.WriteLine($"Segments:");
foreach (TranscribedSegment segment in transcription.Segments)
{
Console.WriteLine($" {segment.Text,90} : {segment.StartTime.TotalMilliseconds,5:0} - {segment.EndTime.TotalMilliseconds,5:0}");
}
Text to Speech (TTS)
using Azure.AI.OpenAI;
using Azure.Identity;
using OpenAI.Audio;
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
AudioClient client = azureClient.GetAudioClient("tts-hd"); //Replace with your Azure OpenAI model deployment
string input = "Testing, testing, 1, 2, 3";
BinaryData speech = client.GenerateSpeech(input, GeneratedSpeechVoice.Alloy);
using FileStream stream = File.OpenWrite($"{Guid.NewGuid()}.mp3");
speech.ToStream().CopyTo(stream);
Chat
AzureOpenAIClient.GetChatClient
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-deployment");
ChatCompletion completion = chatClient.CompleteChat(
[
// System messages represent instructions or other guidance about how the assistant should behave
new SystemChatMessage("You are a helpful assistant that talks like a pirate."),
// User messages represent user input, whether historical or the most recent input
new UserChatMessage("Hi, can you help me?"),
// Assistant messages in a request represent conversation history for responses
new AssistantChatMessage("Arrr! Of course, me hearty! What can I do for ye?"),
new UserChatMessage("What's the best way to train a parrot?"),
]);
Console.WriteLine($"{completion.Role}: {completion.Content[0].Text}");
Stream chat messages
Streaming chat completions use the CompleteChatStreaming and CompleteChatStreamingAsync method, which return a ResultCollection<StreamingChatCompletionUpdate> or AsyncCollectionResult<StreamingChatCompletionUpdate> instead of a ClientResult<ChatCompletion>.
These result collections can be iterated over using foreach or await foreach, with each update arriving as new data is available from the streamed response.
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ChatClient chatClient = azureClient.GetChatClient("my-gpt-4o-deployment");
CollectionResult<StreamingChatCompletionUpdate> completionUpdates = chatClient.CompleteChatStreaming(
[
new SystemChatMessage("You are a helpful assistant that talks like a pirate."),
new UserChatMessage("Hi, can you help me?"),
new AssistantChatMessage("Arrr! Of course, me hearty! What can I do for ye?"),
new UserChatMessage("What's the best way to train a parrot?"),
]);
foreach (StreamingChatCompletionUpdate completionUpdate in completionUpdates)
{
foreach (ChatMessageContentPart contentPart in completionUpdate.ContentUpdate)
{
Console.Write(contentPart.Text);
}
}
Embeddings
AzureOpenAIClient.GetEmbeddingClient
using Azure.AI.OpenAI;
using Azure.Identity;
using OpenAI.Embeddings;
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
EmbeddingClient client = azureClient.GetEmbeddingClient("text-embedding-3-large"); //Replace with your model deployment name
string description = "This is a test embedding";
OpenAIEmbedding embedding = client.GenerateEmbedding(description);
ReadOnlyMemory<float> vector = embedding.ToFloats();
Console.WriteLine(string.Join(", ", vector.ToArray()));
Fine-tuning
Currently not supported with the Azure OpenAI .NET packages.
Batch
Currently not supported with the Azure OpenAI .NET packages.
Images
AzureOpenAIClient.GetImageClient
using Azure.AI.OpenAI;
using Azure.Identity;
using OpenAI.Images;
AzureOpenAIClient azureClient = new(
new Uri("https://your-azure-openai-resource.com"),
new DefaultAzureCredential());
ImageClient client = azureClient.GetImageClient("dall-e-3"); // replace with your model deployment name.
string prompt = "A rabbit eating pancakes.";
ImageGenerationOptions options = new()
{
Quality = GeneratedImageQuality.High,
Size = GeneratedImageSize.W1792xH1024,
Style = GeneratedImageStyle.Vivid,
ResponseFormat = GeneratedImageFormat.Bytes
};
GeneratedImage image = client.GenerateImage(prompt, options);
BinaryData bytes = image.ImageBytes;
using FileStream stream = File.OpenWrite($"{Guid.NewGuid()}.png");
bytes.ToStream().CopyTo(stream);
Completions (legacy)
Not supported with the Azure OpenAI .NET packages.
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 additional 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) | API reference documentation | Package reference documentation Samples
Azure OpenAI API version support
Unlike the Azure OpenAI client libraries for Python and JavaScript, the Azure OpenAI Go library is targeted to a specific Azure OpenAI API version. Having access to the latest API versions impacts feature availability.
Current Azure OpenAI API version target: 2024-10-01-preview
This is defined in the custom_client.go file.
Installation
Install the azopenai and azidentity modules with go get:
go get github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai
# optional
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
Authentication
The azidentity module is used for Azure Active Directory authentication with Azure OpenAI.
package main
import (
"log"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)
func main() {
dac, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
// NOTE: this constructor creates a client that connects to an Azure OpenAI endpoint.
// To connect to the public OpenAI endpoint, use azopenai.NewClientForOpenAI
client, err := azopenai.NewClient("https://<your-azure-openai-host>.openai.azure.com", dac, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
_ = client
}
Audio
Client.GenerateSpeechFromText
ackage main
import (
"context"
"fmt"
"io"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
openAIKey := os.Getenv("OPENAI_API_KEY")
// Ex: "https://api.openai.com/v1"
openAIEndpoint := os.Getenv("OPENAI_ENDPOINT")
modelDeploymentID := "tts-1"
if openAIKey == "" || openAIEndpoint == "" || modelDeploymentID == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(openAIKey)
client, err := azopenai.NewClientForOpenAI(openAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
audioResp, err := client.GenerateSpeechFromText(context.Background(), azopenai.SpeechGenerationOptions{
Input: to.Ptr("i am a computer"),
Voice: to.Ptr(azopenai.SpeechVoiceAlloy),
ResponseFormat: to.Ptr(azopenai.SpeechGenerationResponseFormatFlac),
DeploymentName: to.Ptr("tts-1"),
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
defer audioResp.Body.Close()
audioBytes, err := io.ReadAll(audioResp.Body)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
fmt.Fprintf(os.Stderr, "Got %d bytes of FLAC audio\n", len(audioBytes))
}
Client.GetAudioTranscription
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_WHISPER_API_KEY")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_WHISPER_ENDPOINT")
modelDeploymentID := os.Getenv("AOAI_WHISPER_MODEL")
if azureOpenAIKey == "" || azureOpenAIEndpoint == "" || modelDeploymentID == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
mp3Bytes, err := os.ReadFile("testdata/sampledata_audiofiles_myVoiceIsMyPassportVerifyMe01.mp3")
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetAudioTranscription(context.TODO(), azopenai.AudioTranscriptionOptions{
File: mp3Bytes,
// this will return _just_ the translated text. Other formats are available, which return
// different or additional metadata. See [azopenai.AudioTranscriptionFormat] for more examples.
ResponseFormat: to.Ptr(azopenai.AudioTranscriptionFormatText),
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
fmt.Fprintf(os.Stderr, "Transcribed text: %s\n", *resp.Text)
}
Chat
Client.GetChatCompletions
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_CHAT_COMPLETIONS_API_KEY")
modelDeploymentID := os.Getenv("AOAI_CHAT_COMPLETIONS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_CHAT_COMPLETIONS_ENDPOINT")
if azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
// This is a conversation in progress.
// NOTE: all messages, regardless of role, count against token usage for this API.
messages := []azopenai.ChatRequestMessageClassification{
// You set the tone and rules of the conversation with a prompt as the system role.
&azopenai.ChatRequestSystemMessage{Content: azopenai.NewChatRequestSystemMessageContent("You are a helpful assistant. You will talk like a pirate.")},
// The user asks a question
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("Can you help me?")},
// The reply would come back from the ChatGPT. You'd add it to the conversation so we can maintain context.
&azopenai.ChatRequestAssistantMessage{Content: azopenai.NewChatRequestAssistantMessageContent("Arrrr! Of course, me hearty! What can I do for ye?")},
// The user answers the question based on the latest reply.
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("What's the best way to train a parrot?")},
// from here you'd keep iterating, sending responses back from ChatGPT
}
gotReply := false
resp, err := client.GetChatCompletions(context.TODO(), azopenai.ChatCompletionsOptions{
// This is a conversation in progress.
// NOTE: all messages count against token usage for this API.
Messages: messages,
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, choice := range resp.Choices {
gotReply = true
if choice.ContentFilterResults != nil {
fmt.Fprintf(os.Stderr, "Content filter results\n")
if choice.ContentFilterResults.Error != nil {
fmt.Fprintf(os.Stderr, " Error:%v\n", choice.ContentFilterResults.Error)
}
fmt.Fprintf(os.Stderr, " Hate: sev: %v, filtered: %v\n", *choice.ContentFilterResults.Hate.Severity, *choice.ContentFilterResults.Hate.Filtered)
fmt.Fprintf(os.Stderr, " SelfHarm: sev: %v, filtered: %v\n", *choice.ContentFilterResults.SelfHarm.Severity, *choice.ContentFilterResults.SelfHarm.Filtered)
fmt.Fprintf(os.Stderr, " Sexual: sev: %v, filtered: %v\n", *choice.ContentFilterResults.Sexual.Severity, *choice.ContentFilterResults.Sexual.Filtered)
fmt.Fprintf(os.Stderr, " Violence: sev: %v, filtered: %v\n", *choice.ContentFilterResults.Violence.Severity, *choice.ContentFilterResults.Violence.Filtered)
}
if choice.Message != nil && choice.Message.Content != nil {
fmt.Fprintf(os.Stderr, "Content[%d]: %s\n", *choice.Index, *choice.Message.Content)
}
if choice.FinishReason != nil {
// this choice's conversation is complete.
fmt.Fprintf(os.Stderr, "Finish reason[%d]: %s\n", *choice.Index, *choice.FinishReason)
}
}
if gotReply {
fmt.Fprintf(os.Stderr, "Got chat completions reply\n")
}
}
Client.GetChatCompletionsStream
package main
import (
"context"
"errors"
"fmt"
"io"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_CHAT_COMPLETIONS_API_KEY")
modelDeploymentID := os.Getenv("AOAI_CHAT_COMPLETIONS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_CHAT_COMPLETIONS_ENDPOINT")
if azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
// This is a conversation in progress.
// NOTE: all messages, regardless of role, count against token usage for this API.
messages := []azopenai.ChatRequestMessageClassification{
// You set the tone and rules of the conversation with a prompt as the system role.
&azopenai.ChatRequestSystemMessage{Content: azopenai.NewChatRequestSystemMessageContent("You are a helpful assistant. You will talk like a pirate and limit your responses to 20 words or less.")},
// The user asks a question
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("Can you help me?")},
// The reply would come back from the ChatGPT. You'd add it to the conversation so we can maintain context.
&azopenai.ChatRequestAssistantMessage{Content: azopenai.NewChatRequestAssistantMessageContent("Arrrr! Of course, me hearty! What can I do for ye?")},
// The user answers the question based on the latest reply.
&azopenai.ChatRequestUserMessage{Content: azopenai.NewChatRequestUserMessageContent("What's the best way to train a parrot?")},
// from here you'd keep iterating, sending responses back from ChatGPT
}
resp, err := client.GetChatCompletionsStream(context.TODO(), azopenai.ChatCompletionsStreamOptions{
// This is a conversation in progress.
// NOTE: all messages count against token usage for this API.
Messages: messages,
N: to.Ptr[int32](1),
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
defer resp.ChatCompletionsStream.Close()
gotReply := false
for {
chatCompletions, err := resp.ChatCompletionsStream.Read()
if errors.Is(err, io.EOF) {
break
}
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, choice := range chatCompletions.Choices {
gotReply = true
text := ""
if choice.Delta.Content != nil {
text = *choice.Delta.Content
}
role := ""
if choice.Delta.Role != nil {
role = string(*choice.Delta.Role)
}
fmt.Fprintf(os.Stderr, "Content[%d], role %q: %q\n", *choice.Index, role, text)
}
}
if gotReply {
fmt.Fprintf(os.Stderr, "Got chat completions streaming reply\n")
}
}
Embeddings
Client.GetEmbeddings
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_EMBEDDINGS_API_KEY")
modelDeploymentID := os.Getenv("AOAI_EMBEDDINGS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_EMBEDDINGS_ENDPOINT")
if azureOpenAIKey == "" || modelDeploymentID == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetEmbeddings(context.TODO(), azopenai.EmbeddingsOptions{
Input: []string{"Testing, testing, 1,2,3."},
DeploymentName: &modelDeploymentID,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, embed := range resp.Data {
// embed.Embedding contains the embeddings for this input index.
fmt.Fprintf(os.Stderr, "Got embeddings for input %d\n", *embed.Index)
}
}
Image Generation
Client.GetImageGenerations
package main
import (
"context"
"fmt"
"log"
"net/http"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_DALLE_API_KEY")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_DALLE_ENDPOINT")
azureDeployment := os.Getenv("AOAI_DALLE_MODEL")
if azureOpenAIKey == "" || azureOpenAIEndpoint == "" || azureDeployment == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetImageGenerations(context.TODO(), azopenai.ImageGenerationOptions{
Prompt: to.Ptr("a cat"),
ResponseFormat: to.Ptr(azopenai.ImageGenerationResponseFormatURL),
DeploymentName: &azureDeployment,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, generatedImage := range resp.Data {
// the underlying type for the generatedImage is dictated by the value of
// ImageGenerationOptions.ResponseFormat. In this example we used `azopenai.ImageGenerationResponseFormatURL`,
// so the underlying type will be ImageLocation.
resp, err := http.Head(*generatedImage.URL)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
_ = resp.Body.Close()
fmt.Fprintf(os.Stderr, "Image generated, HEAD request on URL returned %d\n", resp.StatusCode)
}
}
Completions (legacy)
Client.GetChatCompletions
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/Azure/azure-sdk-for-go/sdk/ai/azopenai"
"github.com/Azure/azure-sdk-for-go/sdk/azcore"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
)
func main() {
azureOpenAIKey := os.Getenv("AOAI_COMPLETIONS_API_KEY")
modelDeployment := os.Getenv("AOAI_COMPLETIONS_MODEL")
// Ex: "https://<your-azure-openai-host>.openai.azure.com"
azureOpenAIEndpoint := os.Getenv("AOAI_COMPLETIONS_ENDPOINT")
if azureOpenAIKey == "" || modelDeployment == "" || azureOpenAIEndpoint == "" {
fmt.Fprintf(os.Stderr, "Skipping example, environment variables missing\n")
return
}
keyCredential := azcore.NewKeyCredential(azureOpenAIKey)
// In Azure OpenAI you must deploy a model before you can use it in your client. For more information
// see here: https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource
client, err := azopenai.NewClientWithKeyCredential(azureOpenAIEndpoint, keyCredential, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
resp, err := client.GetCompletions(context.TODO(), azopenai.CompletionsOptions{
Prompt: []string{"What is Azure OpenAI, in 20 words or less"},
MaxTokens: to.Ptr(int32(2048)),
Temperature: to.Ptr(float32(0.0)),
DeploymentName: &modelDeployment,
}, nil)
if err != nil {
// TODO: Update the following line with your application specific error handling logic
log.Printf("ERROR: %s", err)
return
}
for _, choice := range resp.Choices {
fmt.Fprintf(os.Stderr, "Result: %s\n", *choice.Text)
}
}
Error handling
All methods that send HTTP requests return *azcore.ResponseError when these requests fail. ResponseError has error details and the raw response from the service.
Logging
This module uses the logging implementation in azcore. To turn on logging for all Azure SDK modules, set AZURE_SDK_GO_LOGGING to all. By default, the logger writes to stderr. Use the azcore/log package to control log output. For example, logging only HTTP request and response events, and printing them to stdout:
import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
// Print log events to stdout
azlog.SetListener(func(cls azlog.Event, msg string) {
fmt.Println(msg)
})
// Includes only requests and responses in credential logs
azlog.SetEvents(azlog.EventRequest, azlog.EventResponse)
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:
-2024-08-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.12</version>
</dependency>
Authentication
In order to interact with the Azure OpenAI Service 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();
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 service 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 service 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 |
2024-10-01-preview |
Installation
npm install openai
Authentication
There are several ways to authenticate with the Azure OpenAI service 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 to the second argument of the OpenAIClient 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 client = new AzureOpenAI({
endpoint,
apiVersions,
azureADTokenProvider
});
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
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 |
2024-10-01-preview |
Installation
pip install openai
For the latest version:
pip install openai --upgrade
Authentication
import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)
client = AzureOpenAI(
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),
azure_ad_token_provider=token_provider,
api_version="2024-10-21"
)
Audio
audio.speech.create()
This function currently requires a preview API version.
Set api_version="2024-10-01-preview" to use this function.
# from openai import AzureOpenAI
# client = AzureOpenAI()
from pathlib import Path
import os
speech_file_path = Path("speech.mp3")
response = client.audio.speech.create(
model="tts-hd", #Replace with model deployment name
voice="alloy",
input="Testing, testing, 1,2,3."
)
response.write_to_file(speech_file_path)
audio.transcriptions.create()
# from openai import AzureOpenAI
# client = AzureOpenAI()
audio_file = open("speech1.mp3", "rb")
transcript = client.audio.transcriptions.create(
model="whisper", # Replace with model deployment name
file=audio_file
)
print(transcript)
Chat
chat.completions.create()
# from openai import AzureOpenAI
# client = AzureOpenAI()
completion = client.chat.completions.create(
model="gpt-4o", # Replace with your model dpeloyment 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 AzureOpenAI
# client = AzureOpenAI()
completion = client.chat.completions.create(
model="gpt-4o", # Replace with your model dpeloyment 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-services/openai/media/how-to/generated-seattle.png",
}
},
],
}
],
max_tokens=300,
)
print(completion.model_dump_json(indent=2))
Embeddings
embeddings.create()
# from openai import AzureOpenAI
# client = AzureOpenAI()
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
Batch
Batch with Python how-to article
Images
images.generate()
# from openai import AzureOpenAI
# client = AzureOpenAI()
generate_image = client.images.generate(
model="dall-e-3", #replace with your model deployment name
prompt="A rabbit eating pancakes",
n=1,
size="1024x1024",
quality = "hd",
response_format = "url",
style = "vivid"
)
print(generate_image.model_dump_json(indent=2))
Completions (legacy)
completions.create()
# from openai import AzureOpenAI
# client = AzureOpenAI()
legacy_completion = client.completions.create(
model="gpt-35-turbo-instruct", # Replace with model deployment name
prompt="Hello World!",
max_tokens=100,
temperature=0
)
print(legacy_completion.model_dump_json(indent=2))
Error handling
# from openai import AzureOpenAI
# client = AzureOpenAI()
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 responde 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 AzureOpenAI
client = AzureOpenAI(
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
- To see what models are currently supported, check out the Azure OpenAI models page