Table of Contents

Getting started

Prerequisites

Install the NuGet package

dotnet add package OpenAI

Using the client library

usingOpenAI.Chat;ChatClientclient=new(model:"gpt-4o",apiKey:Environment.GetEnvironmentVariable("OPENAI_API_KEY"));ChatCompletioncompletion=client.CompleteChat("Say 'this is a test.'");Console.WriteLine($"[ASSISTANT]:{completion.Content[0].Text}");

Using a custom base URL and API key

usingOpenAI;usingOpenAI.Chat;ChatClientclient=new(model:"MODEL_NAME",credential:newApiKeyCredential(Environment.GetEnvironmentVariable("OPENAI_API_KEY")),options:newOpenAIClientOptions(){Endpoint=newUri("BASE_URL")});

Namespace organization

Using the async API

ChatCompletioncompletion=awaitclient.CompleteChatAsync("Say 'this is a test.'");

Using theOpenAIClient class

usingOpenAI;

OpenAIClientclient=new(Environment.GetEnvironmentVariable("OPENAI_API_KEY"));

AudioClientttsClient=client.GetAudioClient("tts-1");AudioClientwhisperClient=client.GetAudioClient("whisper-1");

How to use dependency injection

builder.Services.AddSingleton<ChatClient>(serviceProvider=>{varapiKey=Environment.GetEnvironmentVariable("OPENAI_API_KEY");varmodel="gpt-4o";returnnewChatClient(model,apiKey);});

[ApiController][Route("api/[controller]")]publicclassChatController:ControllerBase{privatereadonlyChatClient_chatClient;publicChatController(ChatClientchatClient){_chatClient=chatClient;}[HttpPost("complete")]publicasyncTask<IActionResult>CompleteChat([FromBody]stringmessage){ChatCompletioncompletion=await_chatClient.CompleteChatAsync(message);returnOk(new{response=completion.Content[0].Text});}}

How to use chat completions with streaming

CollectionResult<StreamingChatCompletionUpdate>completionUpdates=client.CompleteChatStreaming("Say 'this is a test.'");

Console.Write($"[ASSISTANT]: ");foreach(StreamingChatCompletionUpdatecompletionUpdateincompletionUpdates){if(completionUpdate.ContentUpdate.Count>0){Console.Write(completionUpdate.ContentUpdate[0].Text);}}

AsyncCollectionResult<StreamingChatCompletionUpdate>completionUpdates=client.CompleteChatStreamingAsync("Say 'this is a test.'");Console.Write($"[ASSISTANT]: ");awaitforeach(StreamingChatCompletionUpdatecompletionUpdateincompletionUpdates){if(completionUpdate.ContentUpdate.Count>0){Console.Write(completionUpdate.ContentUpdate[0].Text);}}

How to use chat completions with tools and function calling

privatestaticstringGetCurrentLocation(){// Call the location API here.return"San Francisco";}privatestaticstringGetCurrentWeather(stringlocation,stringunit="celsius"){// Call the weather API here.return$"31{unit}";}

privatestaticreadonlyChatToolgetCurrentLocationTool=ChatTool.CreateFunctionTool(functionName:nameof(GetCurrentLocation),functionDescription:"Get the user's current location");privatestaticreadonlyChatToolgetCurrentWeatherTool=ChatTool.CreateFunctionTool(functionName:nameof(GetCurrentWeather),functionDescription:"Get the current weather in a given location",functionParameters:BinaryData.FromBytes("""        {            "type": "object",            "properties": {                "location": {                    "type": "string",                    "description": "The city and state, e.g. Boston, MA"                },                "unit": {                    "type": "string",                    "enum": [ "celsius", "fahrenheit" ],                    "description": "The temperature unit to use. Infer this from the specified location."                }            },            "required": [ "location" ]        }        """u8.ToArray()));

List<ChatMessage>messages=[newUserChatMessage("What's the weather like today?"),];ChatCompletionOptionsoptions=new(){Tools={getCurrentLocationTool,getCurrentWeatherTool},};

boolrequiresAction;do{requiresAction=false;ChatCompletioncompletion=client.CompleteChat(messages,options);switch(completion.FinishReason){caseChatFinishReason.Stop:{// Add the assistant message to the conversation history.messages.Add(newAssistantChatMessage(completion));break;}caseChatFinishReason.ToolCalls:{// First, add the assistant message with tool calls to the conversation history.messages.Add(newAssistantChatMessage(completion));// Then, add a new tool message for each tool call that is resolved.foreach(ChatToolCalltoolCallincompletion.ToolCalls){switch(toolCall.FunctionName){casenameof(GetCurrentLocation):{stringtoolResult=GetCurrentLocation();messages.Add(newToolChatMessage(toolCall.Id,toolResult));break;}casenameof(GetCurrentWeather):{// The arguments that the model wants to use to call the function are specified as a// stringified JSON object based on the schema defined in the tool definition. Note that// the model may hallucinate arguments too. Consequently, it is important to do the// appropriate parsing and validation before calling the function.usingJsonDocumentargumentsJson=JsonDocument.Parse(toolCall.FunctionArguments);boolhasLocation=argumentsJson.RootElement.TryGetProperty("location",outJsonElementlocation);boolhasUnit=argumentsJson.RootElement.TryGetProperty("unit",outJsonElementunit);if(!hasLocation){thrownewArgumentNullException(nameof(location),"The location argument is required.");}stringtoolResult=hasUnit?GetCurrentWeather(location.GetString(),unit.GetString()):GetCurrentWeather(location.GetString());messages.Add(newToolChatMessage(toolCall.Id,toolResult));break;}default:{// Handle other unexpected calls.thrownewNotImplementedException();}}}requiresAction=true;break;}caseChatFinishReason.Length:thrownewNotImplementedException("Incomplete model output due to MaxTokens parameter or token limit exceeded.");caseChatFinishReason.ContentFilter:thrownewNotImplementedException("Omitted content due to a content filter flag.");caseChatFinishReason.FunctionCall:thrownewNotImplementedException("Deprecated in favor of tool calls.");default:thrownewNotImplementedException(completion.FinishReason.ToString());}}while(requiresAction);

How to use chat completions with structured outputs

List<ChatMessage>messages=[newUserChatMessage("How can I solve 8x + 7 = -23?"),];ChatCompletionOptionsoptions=new(){ResponseFormat=ChatResponseFormat.CreateJsonSchemaFormat(jsonSchemaFormatName:"math_reasoning",jsonSchema:BinaryData.FromBytes("""            {                "type": "object",                "properties": {                    "steps": {                        "type": "array",                        "items": {                            "type": "object",                            "properties": {                                "explanation": { "type": "string" },                                "output": { "type": "string" }                            },                            "required": ["explanation", "output"],                            "additionalProperties": false                        }                    },                    "final_answer": { "type": "string" }                },                "required": ["steps", "final_answer"],                "additionalProperties": false            }            """u8.ToArray()),jsonSchemaIsStrict:true)};ChatCompletioncompletion=client.CompleteChat(messages,options);usingJsonDocumentstructuredJson=JsonDocument.Parse(completion.Content[0].Text);Console.WriteLine($"Final answer:{structuredJson.RootElement.GetProperty("final_answer")}");Console.WriteLine("Reasoning steps:");foreach(JsonElementstepElementinstructuredJson.RootElement.GetProperty("steps").EnumerateArray()){Console.WriteLine($"  - Explanation:{stepElement.GetProperty("explanation")}");Console.WriteLine($"    Output:{stepElement.GetProperty("output")}");}

How to use chat completions with audio

// Chat audio input and output is only supported on specific models, beginning with gpt-4o-audio-previewChatClientclient=new("gpt-4o-audio-preview",Environment.GetEnvironmentVariable("OPENAI_API_KEY"));// Input audio is provided to a request by adding an audio content part to a user messagestringaudioFilePath=Path.Combine("Assets","realtime_whats_the_weather_pcm16_24khz_mono.wav");byte[]audioFileRawBytes=File.ReadAllBytes(audioFilePath);BinaryDataaudioData=BinaryData.FromBytes(audioFileRawBytes);List<ChatMessage>messages=[newUserChatMessage(ChatMessageContentPart.CreateInputAudioPart(audioData,ChatInputAudioFormat.Wav)),];// Output audio is requested by configuring ChatCompletionOptions to include the appropriate// ResponseModalities values and corresponding AudioOptions.ChatCompletionOptionsoptions=new(){ResponseModalities=ChatResponseModalities.Text|ChatResponseModalities.Audio,AudioOptions=new(ChatOutputAudioVoice.Alloy,ChatOutputAudioFormat.Mp3),};ChatCompletioncompletion=client.CompleteChat(messages,options);voidPrintAudioContent(){if(completion.OutputAudioisChatOutputAudiooutputAudio){Console.WriteLine($"Response audio transcript:{outputAudio.Transcript}");stringoutputFilePath=$"{outputAudio.Id}.mp3";using(FileStreamoutputFileStream=File.OpenWrite(outputFilePath)){outputFileStream.Write(outputAudio.AudioBytes);}Console.WriteLine($"Response audio written to file:{outputFilePath}");Console.WriteLine($"Valid on followup requests until:{outputAudio.ExpiresAt}");}}PrintAudioContent();// To refer to past audio output, create an assistant message from the earlier ChatCompletion, use the earlier// response content part, or use ChatMessageContentPart.CreateAudioPart(string) to manually instantiate a part.messages.Add(newAssistantChatMessage(completion));messages.Add("Can you say that like a pirate?");completion=client.CompleteChat(messages,options);PrintAudioContent();

How to use responses with streaming and reasoning

OpenAIResponseClientclient=new(model:"o3-mini",apiKey:Environment.GetEnvironmentVariable("OPENAI_API_KEY"));OpenAIResponseresponse=awaitclient.CreateResponseAsync(userInputText:"What's the optimal strategy to win at poker?",newResponseCreationOptions(){ReasoningOptions=newResponseReasoningOptions(){ReasoningEffortLevel=ResponseReasoningEffortLevel.High,},});awaitforeach(StreamingResponseUpdateupdateinclient.CreateResponseStreamingAsync(userInputText:"What's the optimal strategy to win at poker?",newResponseCreationOptions(){ReasoningOptions=newResponseReasoningOptions(){ReasoningEffortLevel=ResponseReasoningEffortLevel.High,},})){if(updateisStreamingResponseOutputItemAddedUpdateitemUpdate&&itemUpdate.ItemisReasoningResponseItemreasoningItem){Console.WriteLine($"[Reasoning] ({reasoningItem.Status})");}elseif(updateisStreamingResponseOutputItemAddedUpdateitemDone&&itemDone.ItemisReasoningResponseItemreasoningDone){Console.WriteLine($"[Reasoning DONE] ({reasoningDone.Status})");}elseif(updateisStreamingResponseOutputTextDeltaUpdatedelta){Console.Write(delta.Delta);}}

How to use responses with file search

OpenAIResponseClientclient=new(model:"gpt-4o-mini",apiKey:Environment.GetEnvironmentVariable("OPENAI_API_KEY"));ResponseToolfileSearchTool=ResponseTool.CreateFileSearchTool(vectorStoreIds:[ExistingVectorStoreForTest.Id]);OpenAIResponseresponse=awaitclient.CreateResponseAsync(userInputText:"According to available files, what's the secret number?",newResponseCreationOptions(){Tools={fileSearchTool}});foreach(ResponseItemoutputIteminresponse.OutputItems){if(outputItemisFileSearchCallResponseItemfileSearchCall){Console.WriteLine($"[file_search] ({fileSearchCall.Status}):{fileSearchCall.Id}");foreach(stringqueryinfileSearchCall.Queries){Console.WriteLine($"  -{query}");}}elseif(outputItemisMessageResponseItemmessage){Console.WriteLine($"[{message.Role}]{message.Content.FirstOrDefault()?.Text}");}}

How to use responses with web search

OpenAIResponseClientclient=new(model:"gpt-4o-mini",apiKey:Environment.GetEnvironmentVariable("OPENAI_API_KEY"));OpenAIResponseresponse=awaitclient.CreateResponseAsync(userInputText:"What's a happy news headline from today?",newResponseCreationOptions(){Tools={ResponseTool.CreateWebSearchTool()},});foreach(ResponseItemiteminresponse.OutputItems){if(itemisWebSearchCallResponseItemwebSearchCall){Console.WriteLine($"[Web search invoked]({webSearchCall.Status}){webSearchCall.Id}");}elseif(itemisMessageResponseItemmessage){Console.WriteLine($"[{message.Role}]{message.Content?.FirstOrDefault()?.Text}");}}

How to generate text embeddings

usingOpenAI.Embeddings;EmbeddingClientclient=new("text-embedding-3-small",Environment.GetEnvironmentVariable("OPENAI_API_KEY"));stringdescription="Best hotel in town if you like luxury hotels. They have an amazing infinity pool, a spa,"+" and a really helpful concierge. The location is perfect -- right downtown, close to all the tourist"+" attractions. We highly recommend this hotel.";OpenAIEmbeddingembedding=client.GenerateEmbedding(description);ReadOnlyMemory<float>vector=embedding.ToFloats();

EmbeddingGenerationOptionsoptions=new(){Dimensions=512};OpenAIEmbeddingembedding=client.GenerateEmbedding(description,options);

How to generate images

usingOpenAI.Images;ImageClientclient=new("dall-e-3",Environment.GetEnvironmentVariable("OPENAI_API_KEY"));

stringprompt="The concept for a living room that blends Scandinavian simplicity with Japanese minimalism for"+" a serene and cozy atmosphere. It's a space that invites relaxation and mindfulness, with natural light"+" and fresh air. Using neutral tones, including colors like white, beige, gray, and black, that create a"+" sense of harmony. Featuring sleek wood furniture with clean lines and subtle curves to add warmth and"+" elegance. Plants and flowers in ceramic pots adding color and life to a space. They can serve as focal"+" points, creating a connection with nature. Soft textiles and cushions in organic fabrics adding comfort"+" and softness to a space. They can serve as accents, adding contrast and texture.";ImageGenerationOptionsoptions=new(){Quality=GeneratedImageQuality.High,Size=GeneratedImageSize.W1792xH1024,Style=GeneratedImageStyle.Vivid,ResponseFormat=GeneratedImageFormat.Bytes};

GeneratedImageimage=client.GenerateImage(prompt,options);BinaryDatabytes=image.ImageBytes;

usingFileStreamstream=File.OpenWrite($"{Guid.NewGuid()}.png");bytes.ToStream().CopyTo(stream);

How to transcribe audio

usingOpenAI.Audio;AudioClientclient=new("whisper-1",Environment.GetEnvironmentVariable("OPENAI_API_KEY"));stringaudioFilePath=Path.Combine("Assets","audio_houseplant_care.mp3");AudioTranscriptionOptionsoptions=new(){ResponseFormat=AudioTranscriptionFormat.Verbose,TimestampGranularities=AudioTimestampGranularities.Word|AudioTimestampGranularities.Segment,};AudioTranscriptiontranscription=client.TranscribeAudio(audioFilePath,options);Console.WriteLine("Transcription:");Console.WriteLine($"{transcription.Text}");Console.WriteLine();Console.WriteLine($"Words:");foreach(TranscribedWordwordintranscription.Words){Console.WriteLine($"{word.Word,15} :{word.StartTime.TotalMilliseconds,5:0} -{word.EndTime.TotalMilliseconds,5:0}");}Console.WriteLine();Console.WriteLine($"Segments:");foreach(TranscribedSegmentsegmentintranscription.Segments){Console.WriteLine($"{segment.Text,90} :{segment.StartTime.TotalMilliseconds,5:0} -{segment.EndTime.TotalMilliseconds,5:0}");}

How to use assistants with retrieval augmented generation (RAG)

usingOpenAI.Assistants;usingOpenAI.Files;OpenAIClientopenAIClient=new(Environment.GetEnvironmentVariable("OPENAI_API_KEY"));OpenAIFileClientfileClient=openAIClient.GetOpenAIFileClient();AssistantClientassistantClient=openAIClient.GetAssistantClient();

usingStreamdocument=BinaryData.FromBytes("""    {        "description": "This document contains the sale history data for Contoso products.",        "sales": [            {                "month": "January",                "by_product": {                    "113043": 15,                    "113045": 12,                    "113049": 2                }            },            {                "month": "February",                "by_product": {                    "113045": 22                }            },            {                "month": "March",                "by_product": {                    "113045": 16,                    "113055": 5                }            }        ]    }    """u8.ToArray()).ToStream();

OpenAIFilesalesFile=fileClient.UploadFile(document,"monthly_sales.json",FileUploadPurpose.Assistants);

AssistantCreationOptionsassistantOptions=new(){Name="Example: Contoso sales RAG",Instructions="You are an assistant that looks up sales data and helps visualize the information based"+" on user queries. When asked to generate a graph, chart, or other visualization, use"+" the code interpreter tool to do so.",Tools={newFileSearchToolDefinition(),newCodeInterpreterToolDefinition(),},ToolResources=new(){FileSearch=new(){NewVectorStores={newVectorStoreCreationHelper([salesFile.Id]),}}},};Assistantassistant=assistantClient.CreateAssistant("gpt-4o",assistantOptions);

ThreadCreationOptionsthreadOptions=new(){InitialMessages={"How well did product 113045 sell in February? Graph its trend over time."}};ThreadRunthreadRun=assistantClient.CreateThreadAndRun(assistant.Id,threadOptions);

do{Thread.Sleep(TimeSpan.FromSeconds(1));threadRun=assistantClient.GetRun(threadRun.ThreadId,threadRun.Id);}while(!threadRun.Status.IsTerminal);

CollectionResult<ThreadMessage>messages=assistantClient.GetMessages(threadRun.ThreadId,newMessageCollectionOptions(){Order=MessageCollectionOrder.Ascending});foreach(ThreadMessagemessageinmessages){Console.Write($"[{message.Role.ToString().ToUpper()}]: ");foreach(MessageContentcontentIteminmessage.Content){if(!string.IsNullOrEmpty(contentItem.Text)){Console.WriteLine($"{contentItem.Text}");if(contentItem.TextAnnotations.Count>0){Console.WriteLine();}// Include annotations, if any.foreach(TextAnnotationannotationincontentItem.TextAnnotations){if(!string.IsNullOrEmpty(annotation.InputFileId)){Console.WriteLine($"* File citation, file ID:{annotation.InputFileId}");}if(!string.IsNullOrEmpty(annotation.OutputFileId)){Console.WriteLine($"* File output, new file ID:{annotation.OutputFileId}");}}}if(!string.IsNullOrEmpty(contentItem.ImageFileId)){OpenAIFileimageInfo=fileClient.GetFile(contentItem.ImageFileId);BinaryDataimageBytes=fileClient.DownloadFile(contentItem.ImageFileId);usingFileStreamstream=File.OpenWrite($"{imageInfo.Filename}.png");imageBytes.ToStream().CopyTo(stream);Console.WriteLine($"<image:{imageInfo.Filename}.png>");}}Console.WriteLine();}

[USER]: How well did product 113045 sell in February? Graph its trend over time.[ASSISTANT]: Product 113045 sold 22 units in February【4:0†monthly_sales.json】.Now, I will generate a graph to show its sales trend over time.* File citation, file ID: file-hGOiwGNftMgOsjbynBpMCPFn[ASSISTANT]: <image: 015d8e43-17fe-47de-af40-280f25452280.png>The sales trend for Product 113045 over the past three months shows that:- In January, 12 units were sold.- In February, 22 units were sold, indicating significant growth.- In March, sales dropped slightly to 16 units.The graph above visualizes this trend, showing a peak in sales during February.

How to use assistants with streaming and vision

OpenAIClientopenAIClient=new(Environment.GetEnvironmentVariable("OPENAI_API_KEY"));OpenAIFileClientfileClient=openAIClient.GetOpenAIFileClient();AssistantClientassistantClient=openAIClient.GetAssistantClient();

OpenAIFilepictureOfAppleFile=fileClient.UploadFile(Path.Combine("Assets","images_apple.png"),FileUploadPurpose.Vision);UrilinkToPictureOfOrange=new("https://raw.githubusercontent.com/openai/openai-dotnet/refs/heads/main/examples/Assets/images_orange.png");

Assistantassistant=assistantClient.CreateAssistant("gpt-4o",newAssistantCreationOptions(){Instructions="When asked a question, attempt to answer very concisely. "+"Prefer one-sentence answers whenever feasible."});AssistantThreadthread=assistantClient.CreateThread(newThreadCreationOptions(){InitialMessages={newThreadInitializationMessage(MessageRole.User,["Hello, assistant! Please compare these two images for me:",MessageContent.FromImageFileId(pictureOfAppleFile.Id),MessageContent.FromImageUri(linkToPictureOfOrange),]),}});

CollectionResult<StreamingUpdate>streamingUpdates=assistantClient.CreateRunStreaming(thread.Id,assistant.Id,newRunCreationOptions(){AdditionalInstructions="When possible, try to sneak in puns if you're asked to compare things.",});

foreach(StreamingUpdatestreamingUpdateinstreamingUpdates){if(streamingUpdate.UpdateKind==StreamingUpdateReason.RunCreated){Console.WriteLine($"--- Run started! ---");}if(streamingUpdateisMessageContentUpdatecontentUpdate){Console.Write(contentUpdate.Text);}}

--- Run started! ---The first image depicts a multicolored apple with a blend of red and green hues, while the second image shows an orange with a bright, textured orange peel; one might say it’s comparing apples to oranges!

How to work with Azure OpenAI

AzureOpenAIClientazureClient=new(newUri("https://your-azure-openai-resource.com"),newDefaultAzureCredential());ChatClientchatClient=azureClient.GetChatClient("my-gpt-35-turbo-deployment");ChatCompletioncompletion=chatClient.CompleteChat([// System messages represent instructions or other guidance about how the assistant should behavenewSystemChatMessage("You are a helpful assistant that talks like a pirate."),// User messages represent user input, whether historical or the most recen tinputnewUserChatMessage("Hi, can you help me?"),// Assistant messages in a request represent conversation history for responsesnewAssistantChatMessage("Arrr! Of course, me hearty! What can I do for ye?"),newUserChatMessage("What's the best way to train a parrot?"),]);Console.WriteLine($"{completion.Role}:{completion.Content[0].Text}");

Advanced scenarios

Using protocol methods

ChatClientclient=new("gpt-4o",Environment.GetEnvironmentVariable("OPENAI_API_KEY"));BinaryDatainput=BinaryData.FromBytes("""    {       "model": "gpt-4o",       "messages": [           {               "role": "user",               "content": "Say 'this is a test.'"           }       ]    }    """u8.ToArray());usingBinaryContentcontent=BinaryContent.Create(input);ClientResultresult=client.CompleteChat(content);BinaryDataoutput=result.GetRawResponse().Content;usingJsonDocumentoutputAsJson=JsonDocument.Parse(output.ToString());stringmessage=outputAsJson.RootElement.GetProperty("choices"u8)[0].GetProperty("message"u8).GetProperty("content"u8).GetString();Console.WriteLine($"[ASSISTANT]:{message}");

Mock a client for testing

publicboolContainsSecretWord(AudioClientclient,stringaudioFilePath,stringsecretWord){AudioTranscriptiontranscription=client.TranscribeAudio(audioFilePath);returntranscription.Text.Contains(secretWord);}

// Instantiate mocks and the AudioTranscription object.Mock<AudioClient>mockClient=new();Mock<ClientResult<AudioTranscription>>mockResult=new(null,Mock.Of<PipelineResponse>());AudioTranscriptiontranscription=OpenAIAudioModelFactory.AudioTranscription(text:"I swear I saw an apple flying yesterday!");// Set up mocks' properties and methods.mockResult.SetupGet(result=>result.Value).Returns(transcription);mockClient.Setup(client=>client.TranscribeAudio(It.IsAny<string>(),It.IsAny<AudioTranscriptionOptions>())).Returns(mockResult.Object);// Perform validation.AudioClientclient=mockClient.Object;boolcontainsSecretWord=ContainsSecretWord(client,"<audioFilePath>","apple");Assert.That(containsSecretWord,Is.True);

Automatically retrying errors

Observability