openai/openai-dotnet

openai/openai-dotnet

Description: The official .NET library for the OpenAI API

Language: C#

License: MIT

Stars: 2626

Forks: 400

Open issues: 56

Created: 2024-04-25T23:27:40Z

Pushed: 2026-06-10T17:21:25Z

Default branch: main

Fork: no

Archived: no

README:

OpenAI .NET API library

The OpenAI .NET library provides convenient access to the OpenAI REST API from .NET applications.

It is generated from our OpenAPI specification in collaboration with Microsoft.

Table of Contents

• [Getting started](#getting-started)
• [Prerequisites](#prerequisites)
• [Install the NuGet package](#install-the-nuget-package)
• [Using the client library](#using-the-client-library)
• [Namespace organization](#namespace-organization)
• [Using the async API](#using-the-async-api)
• [Using the OpenAIClient class](#using-the-openaiclient-class)
• [How to use dependency injection](#how-to-use-dependency-injection)
• [How to use chat completions with streaming](#how-to-use-chat-completions-with-streaming)
• [How to use chat completions with tools and function calling](#how-to-use-chat-completions-with-tools-and-function-calling)
• [How to use chat completions with structured outputs](#how-to-use-chat-completions-with-structured-outputs)
• [How to use chat completions with audio](#how-to-use-chat-completions-with-audio)
• [How to use responses with streaming and reasoning](#how-to-use-responses-with-streaming-and-reasoning)
• [How to use responses with file search](#how-to-use-responses-with-file-search)
• [How to use responses with web search](#how-to-use-responses-with-web-search)
• [How to generate text embeddings](#how-to-generate-text-embeddings)
• [How to generate images](#how-to-generate-images)
• [How to transcribe audio](#how-to-transcribe-audio)
• [How to use assistants with retrieval augmented generation (RAG)](#how-to-use-assistants-with-retrieval-augmented-generation-rag)
• [How to use assistants with streaming and vision](#how-to-use-assistants-with-streaming-and-vision)
• [How to work with Azure OpenAI](#how-to-work-with-azure-openai)
• [Advanced scenarios](#advanced-scenarios)
• [Using protocol methods](#using-protocol-methods)
• [Mock a client for testing](#mock-a-client-for-testing)
• [Automatically retrying errors](#automatically-retrying-errors)
• [Observability](#observability)

Getting started

Prerequisites

To call the OpenAI REST API, you will need an API key. To obtain one, first create a new OpenAI account or log in. Next, navigate to the API key page and select "Create new secret key", optionally naming the key. Make sure to save your API key somewhere safe and do not share it with anyone.

Install the NuGet package

Add the client library to your .NET project by installing the NuGet package via your IDE or by running the following command in the .NET CLI:

dotnet add package OpenAI

Note that the code examples included below were written using .NET 10. The OpenAI .NET library is compatible with all .NET Standard 2.0 applications, but the syntax used in some of the code examples in this document may depend on newer language features.

Using the client library

The full API of this library can be found in the OpenAI.netstandard2.0.cs file, and there are many code examples to help. For instance, the following snippet illustrates the basic use of the chat completions API:

ChatClient client = new(model: "gpt-5.1", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY"));

ChatCompletion completion = client.CompleteChat("Say 'this is a test.'");
Console.WriteLine($"[ASSISTANT]: {completion.Content[0].Text}");

While you can pass your API key directly as a string, it is highly recommended that you keep it in a secure location and instead access it via an environment variable or configuration file as shown above to avoid storing it in source control.

Using a custom base URL and API key

If you need to connect to an alternative API endpoint (for example, a proxy or self-hosted OpenAI-compatible LLM), you can specify a custom base URL and API key using the ApiKeyCredential and OpenAIClientOptions:

ChatClient client = new(
model: "MODEL_NAME",
credential: new ApiKeyCredential(Environment.GetEnvironmentVariable("OPENAI_API_KEY")),
options: new OpenAIClientOptions()
{
Endpoint = new Uri("https://YOUR_BASE_URL")
});

Replace MODEL_NAME with your model name and BASE_URL with your endpoint URI. This is useful when working with OpenAI-compatible APIs or custom deployments.

Namespace organization

The library is organized into namespaces by feature areas in the OpenAI REST API. Each namespace contains a corresponding client class.

| Namespace | Client class | | ------------------------------|------------------------------| | OpenAI.Assistants | AssistantClient | | OpenAI.Audio | AudioClient | | OpenAI.Batch | BatchClient | | OpenAI.Chat | ChatClient | | OpenAI.Embeddings | EmbeddingClient | | OpenAI.Evals | EvaluationClient | | OpenAI.FineTuning | FineTuningClient | | OpenAI.Files | OpenAIFileClient | | OpenAI.Images | ImageClient | | OpenAI.Models | OpenAIModelClient | | OpenAI.Moderations | ModerationClient | | OpenAI.Realtime | RealtimeClient | | OpenAI.Responses | ResponsesClient | | OpenAI.VectorStores | VectorStoreClient |

Using the async API

Every client method that performs a synchronous API call has an asynchronous variant in the same client class. For instance, the asynchronous variant of the ChatClient's CompleteChat method is CompleteChatAsync. To rewrite the call above using the asynchronous counterpart, simply await the call to the corresponding async variant:

ChatCompletion completion = await client.CompleteChatAsync("Say 'this is a test.'");

Using the OpenAIClient class

In addition to the namespaces mentioned above, there is also the parent OpenAI namespace itself:

using OpenAI;

This namespace contains the…