openai-dotnet: the official .NET client for the OpenAI API

What openai-dotnet actually replaces

If you are writing C# and calling the OpenAI REST API, the default path is HttpClient plus your own request and response models. That means hand-maintaining JSON shapes for chat completions, embeddings, files, batches, vector stores and the rest, and re-checking them whenever the API changes. openai-dotnet removes that work by being generated from the OpenAI OpenAPI specification, in collaboration with Microsoft, so the types track the specification rather than a maintainer's reading of it. The README states it plainly: the library "provides convenient access to the OpenAI REST API from .NET applications."

The audience is narrow and worth stating. This is for .NET developers, and the README notes the code examples were written using .NET 10 while the library itself is compatible with all .NET Standard 2.0 applications. That split matters: you can consume the package from an older target, but the syntax in the documentation may use language features your project cannot compile. The library is published on NuGet under the package name OpenAI and licensed MIT.

One client class per feature area

The organisation is namespace-per-feature, and each namespace holds a matching client class. OpenAI.Chat contains ChatClient, OpenAI.Embeddings contains EmbeddingClient, OpenAI.Images contains ImageClient, and so on through Assistants, Audio, Batch, Evals, FineTuning, Files, Models, Moderations, Realtime, Responses and VectorStores. The README includes the full mapping table. You do not construct a single god-object and reach into it; you instantiate the client for the area you need.

Every synchronous method has an asynchronous variant in the same class. CompleteChat pairs with CompleteChatAsync, and the documented rewrite is to await the async variant. That is a mechanical convention rather than a separate async API, so you can move a call between the two forms without changing which client you hold. The public API listings live in the api/ folder, organised by target framework, which is the reference to consult when the README snippet is not precise enough about a signature. For anything the README does not cover, examples/ is split by area (Chat, Responses, Audio, Images, VectorStore, Realtime, Assistants, Embeddings, Conversations, MutualTls and an aspnet-core sample).

Install the OpenAI NuGet package and make a first call

The install step is a single CLI command from the README. Run it in the project directory that should take the dependency:

dotnet add package OpenAI

Before any call you need an API key. The README directs you to create an OpenAI account, open the API key page, and select "Create new secret key". The repository's .env.sample shows the expected variable name and a test-mode switch:

OPENAI_API_KEY=<< YOUR API KEY >>
CLIENTMODEL_TEST_MODE=Playback

The README's basic chat example reads the key from the environment rather than embedding it, and prints the assistant text. The model name in the snippet is gpt-5.1:

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}");

If you are not pointing at api.openai.com, the README documents a custom endpoint through ApiKeyCredential and OpenAIClientOptions. This is the path for a proxy, a self-hosted OpenAI-compatible server, or an Azure OpenAI deployment:

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 and the base URL with your own values. The README does not document what happens when the endpoint speaks a partially compatible dialect, so treat compatibility as something you verify against your own server rather than assume.

The [Experimental] attribute is a compile-time gate, not a warning

Some client APIs are marked with [Experimental] while their .NET design is still evolving. The README is explicit about the consequence: using one produces a compiler error that you must explicitly suppress for its diagnostic ID. This is a stronger signal than a deprecation warning. It means an experimental surface cannot slip into a codebase by accident, and it also means an upgrade can turn a previously compiling call into a build failure if the attribute is applied to something you already use.

The project documents the lifecycle rather than leaving it implicit. docs/FeatureLifecycle.md describes how OpenAI .NET APIs are introduced and promoted to stable, and the README links to Microsoft's Preview APIs guidance for the general .NET pattern. If you are pinning a version and building on a feature that is still experimental, read that lifecycle document before you plan around the API shape. The README does not promise a timeline for promotion, so the only concrete signal available is the attribute itself plus the changelog.

Release cadence and what an upgrade costs

Releases are frequent. The recent list shows OpenAI_2.13.0 on 2026-08-10, OpenAI_2.12.0 on 2026-07-01, and a pre-release tagged OpenAI_2.11.0-oidc.test1 on 2026-06-19, with the last push to the repository on 2026-09-14. Monthly minor bumps plus test-tagged pre-releases are the pattern, which is what you would expect from a library generated out of a moving OpenAPI specification. The practical cost is that the upgrade surface is continuous rather than occasional.

Two things reduce that cost. First, CHANGELOG.md sits at the repository root, so the diff between your pinned version and the next one is readable before you bump. Second, the api/ folder is organised by target framework, which lets you see whether a signature you depend on changed without reading source. What the README does not document is a rollback procedure or a long-term support policy for older majors, so pinning an exact version and reading the changelog is the only documented way to control the upgrade.

There is also a build-time dependency worth knowing about. The repository root contains codegen/ and a package.json whose name is openai-tsp and whose workspaces list points at codegen. That is the generation pipeline, not something a consumer installs, but it tells you where type changes originate: the specification and the generator, not hand edits in the C# tree.

On licensing, the repository carries an MIT licence at the root. That is permissive and places few conditions on redistribution, but it also means the library ships without warranty, and the terms you accept when calling OpenAI's API are governed by your OpenAI account, not by this repository. This is a description of what the repository states, not legal advice.

When openai-dotnet is the wrong choice

The clearest case against it is a non-.NET stack. Nothing here helps a Python or TypeScript service, and the related search traffic around Azure OpenAI SDKs in other languages reflects exactly that split. If your team is polyglot and standardising on one client shape, this package is the .NET-only branch of that decision.

A subtler case is a project that needs a fully stable API surface across every feature it uses. Because experimental APIs raise a compiler error until you suppress the diagnostic, a codebase that suppresses broadly has traded away the guard rail the attribute provides. Suppressing per call site keeps the signal; suppressing at the project level does not.

Finally, if you only need one endpoint and you already have a hardened HTTP pipeline with your own retry, logging and serialisation conventions, the value of generated types is smaller. The README covers automatic retrying of errors and observability as advanced scenarios, so the library does address those concerns, but a team with an established pipeline should weigh whether adopting a second convention is worth it.

For comparison, the closest alternative in .NET is Azure.AI.OpenAI, the Azure SDK client. The difference is in the endpoint model rather than the feature list: this library defaults to the OpenAI API and lets you redirect with OpenAIClientOptions.Endpoint, while the Azure client is built around an Azure OpenAI resource. The README documents an Azure OpenAI section, so the two are not mutually exclusive, but the default configuration and credential story differ.

Editorial conclusion

Adopt openai-dotnet if you are building a .NET application that calls OpenAI models or an OpenAI-compatible endpoint and you want typed clients and async variants for every call rather than hand-written HTTP. Do not adopt it if your target runtime cannot take a .NET Standard 2.0 dependency, or if you need a stable API surface for every feature you touch, because parts of the client are marked [Experimental] and require an explicit suppression. Before committing, check three things in the repository: the api/ folder for the exact signatures in your target framework, docs/FeatureLifecycle.md for how an experimental API is promoted to stable, and the CHANGELOG.md for what changed between the release you pin and the next one, since releases arrive on a monthly cadence.

Frequently asked questions

Official sources

1. License: MIT
2. openai/openai-dotnet on GitHub
3. Project website
4. README
5. Releases