Betalgo.Ranul.OpenAI: a .NET client for the OpenAI API, and what v9.2.0 changes

What Betalgo.Ranul.OpenAI is for in a .NET codebase

The library exists so that a C# application does not have to hand-roll HTTP calls, JSON serialization and error handling against the OpenAI API. The README describes it as "a .NET Library for accessing OpenAI's API, provided as a community library." That word community matters: this is not an OpenAI-published SDK, and the README's own Notes section says that "not all methods have been thoroughly tested or fully documented" and that the author cannot accept responsibility for damage caused by using the library.

The audience is a .NET developer who already has an API key and wants typed request and response objects. The library covers chat completions, image generation and editing, and Whisper transcription, based on the topics listed on the repository and the changelog entries. It also has an experimental utilities package, Betalgo.OpenAI.Utilities, kept separate from the core library. If you are writing a small script in Python, this is the wrong tool by definition; if you are inside an ASP.NET Core service and want dependency injection, it is aimed at you.

How the service, options and dependency injection fit together

The architecture is a single service interface, IOpenAIService, with grouped sub-services for each API area. You construct it either directly or through the DI container. The README shows the direct path with an OpenAIOptions object holding the API key, and the DI path with AddOpenAIService, which reads an OpenAIServiceOptions section from configuration. After registration you resolve IOpenAIService from the service provider.

Two details are easy to miss. First, the options type name differs between the two paths in the README: the direct constructor takes OpenAIOptions, while the configuration section is named OpenAIServiceOptions. Second, there is an optional default model, set with SetDefaultModelId, so individual calls do not have to repeat the model id. The changelog for 9.2.0 also mentions new response base types, ResponseBase and ResponseBaseHeaderValues, with improved header parsing and usage exposure, which suggests the library is moving toward surfacing rate-limit and usage headers in a structured way rather than leaving them buried in the raw HTTP response.

Installing the package and sending a first chat completion

The package id changed. The README warns in bold that Betalgo.OpenAI is now Betalgo.Ranul.OpenAI, so an existing project referencing the old id will not pick up the new releases. Install from the Package Manager console:

Install-Package Betalgo.Ranul.OpenAI

For dependency injection, the README shows a secrets.json entry with the key, an optional Organization, and an optional UseBeta flag, then a single registration call in Program.cs:

serviceCollection.AddOpenAIService();

Alternatively you can pass settings inline and read the key from an environment variable, which keeps the secret out of the repository:

serviceCollection.AddOpenAIService(settings => { settings.ApiKey = Environment.GetEnvironmentVariable("MY_OPEN_AI_API_KEY"); });

The first real call is a chat completion. The README's sample builds a message list with system, user and assistant turns, sets the model, and checks the Successful flag before reading the content:

var completionResult = await openAiService.ChatCompletion.CreateCompletion(new ChatCompletionCreateRequest
{
    Messages = new List<ChatMessage>
    {
        ChatMessage.FromSystem("You are a helpful assistant."),
        ChatMessage.FromUser("Who won the world series in 2020?")
    },
    Model = Models.Gpt_4o,
});

If the call succeeds you should see the assistant text on completionResult.Choices.First().Message.Content. If it fails, Successful is false and you inspect the error on the result rather than catching an exception. That pattern, a result object with a boolean, is consistent across the samples and is worth knowing before you write your own error handling.

The 9.2.0 Contracts split is the real upgrade risk

The changelog for 9.2.0 introduces Betalgo.Ranul.OpenAI.Contracts as a project for centralized request and response models, enums and value types. Several public types were replaced: CreateImageRequest, CreateImageEditRequest and CreateImageVariationRequest moved to Contracts equivalents; VoiceEnum became Voice; MessageRole became ChatCompletionRole or AssistantMessageRole, depending on context. Image enums were reorganized under Betalgo.Ranul.OpenAI.Contracts.Enums.Image, with new value types such as ImageOutputFormat, ImageSize and ImageModeration.

The changelog is explicit that this is "the first step of a gradual migration" and that "changes are kept minimal and may evolve after testing." It also says edit and variation still return legacy responses for now, so the image API is in a half-migrated state. For a team that pins versions this is manageable; for a team that floats on the latest minor, it means a compile break with no deprecation window. The repository does link a dedicated Contracts Upgrade Guide on the wiki, which is the document to read before touching the package reference.

A separate fix in 9.2.4 addresses function tool schema generation, where parameters now always emit a JSON Schema type of "object" to avoid invalid_function_parameters errors such as a schema reported as type "None". If you use function calling, that entry is the reason to be on 9.2.4 or later rather than 9.2.0.

Where the library is a poor fit

The README's own caution about the sample project is the clearest limitation. It says some test methods "may result in unintended consequences such as file deletion or fine-tuning" and recommends using a separate account rather than a primary one while experimenting with OpenAI.Playground. A playground that can delete files and models on a live account is not something to point at production credentials, and it signals how much of the surface is exercised by tests that mutate remote state.

The documentation gap is the second limitation, stated plainly in the Notes section. If you need a guarantee that every endpoint is documented and covered, this repository does not offer one. The wiki carries a Feature Availability table, which is the honest place to check whether the specific endpoint you need is implemented, rather than assuming from the package description.

Finally, consider the maintenance picture. The last push to the default branch was on 2026-03-21, and the most recent release listed is v9.1.0 from 2025-07-11, while the changelog describes 9.2.0 and 9.2.4. That means the changelog runs ahead of the listed releases, so the version you can actually pull from NuGet may not match the newest entry in the changelog. Check nuget.org for the real published version before planning an upgrade.

How this differs from the official OpenAI .NET library

The obvious alternative is the official OpenAI .NET client, and the difference is one of governance rather than features. The official library is maintained by OpenAI, so its release cadence and its type names track the API vendor directly. Betalgo.Ranul.OpenAI is a community project maintained by Betalgo Ranul with contributors and sponsors listed in the README, and its 9.2.0 Contracts reorganization is an internal design decision, not something dictated by the API.

That cuts both ways. A community library can move faster on conveniences the official client does not prioritize, and the README points to a Realtime API wiki page as a new addition. It can also break its own public types between minor versions, which is exactly what the 9.2.0 changelog describes. If your project can absorb a rename every few releases and you want the DI registration and result-object style shown above, this library is a reasonable choice. If you need type stability across upgrades and a single vendor to hold responsible, the official client is the safer default.

Licence and the cost of staying current

The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive enough for closed-source products. This is a description of the licence text, not legal advice; if your organization has rules about third-party dependencies, run the MIT terms past whoever handles that.

The upgrade cost is the part that does not show up in the licence. Every minor release in the 9.x line appears to carry renames: 9.0.x to 9.1.0 added usage tracking for image generation and expanded FunctionParameters with MultipleOf and Minimum constraints, and 9.1.0 to 9.2.0 moved whole model families into Contracts. The wiki maintains a Migration Guide for breaking changes, and the Contracts Upgrade Guide is separate again. Budget for reading both before each upgrade, and pin the package version in your project file so an unattended restore does not pull a rename into a build.

Editorial conclusion

Adopt it if you are building a .NET service that needs chat completions, image generation or Whisper transcription and you want a single NuGet package instead of hand-written HttpClient calls. Do not adopt it if you need a stability guarantee across minor versions, because 9.2.0 moves request and response models into Betalgo.Ranul.OpenAI.Contracts and the changelog calls that migration gradual. Before upgrading, read the Contracts Upgrade Guide on the wiki and check which of your image request types are still legacy. Verify first that the package id Betalgo.Ranul.OpenAI is the one your project references, not the older Betalgo.OpenAI.

Frequently asked questions

Official sources

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