Universal.OpenAI.Client 4.2.0

Universal.OpenAI.Client

A simple .NET client library for OpenAI's API, supporting commonly used features including Chat Completions, Responses API, streaming, tools, structured outputs, and more.

Quick Start

using Universal.OpenAI.Client;
using Universal.OpenAI.Client.V1.Chat;

using var client = new OpenAIClient("your-api-key");
var response = await client.V1.Chat.CreateCompletionAsync(new CreateCompletionRequest
{
    Model = Models.Gpt55,
    Messages = [
        new SystemMessage("You are a helpful assistant."),
        new UserMessage("Hello, how are you?")
    ]
});

Console.WriteLine(response.Choices[0].Message.Content);

Features

Chat Completions

Create chat completions with support for various message types:

var response = await client.V1.Chat.CreateCompletionAsync(new CreateCompletionRequest
{
    Model = Models.Gpt55,
    Messages = [
        new SystemMessage("You are a helpful assistant."),
        new UserMessage("Tell me a joke."),
        new AssistantMessage("Why don't scientists trust atoms? Because they make up everything!"),
        new UserMessage("That's funny! Tell me another one.")
    ]
});

Streaming Responses

Get real-time streaming responses:

await foreach (var chunk in client.V1.Chat.CreateCompletionStreamingAsync(new CreateCompletionRequest
{
    Model = Models.Gpt55,
    Messages = [new UserMessage("Write a short story.")],
    Stream = true
}))
{
    if (chunk.Choices?[0]?.Delta?.Content != null)
    {
        Console.Write(chunk.Choices[0].Delta.Content);
    }
}

Structured JSON Output

Enforce JSON responses with custom schemas:

var response = await client.V1.Chat.CreateCompletionAsync(new CreateCompletionRequest
{
    Model = Models.Gpt55,
    Messages = [new UserMessage("Analyze this text for sentiment.")],
    ResponseFormat = ResponseFormat.FromJsonSchema("sentiment_analysis", new JsonSchema
    {
        Type = "object",
        Properties = new Dictionary<string, JsonSchema>
        {
            ["sentiment"] = new JsonSchema
            {
                Type = "string",
                Description = "The sentiment of the text",
                Enum = new[] { "positive", "negative", "neutral" }
            },
            ["confidence"] = new JsonSchema
            {
                Type = "number",
                Description = "Confidence score between 0 and 1"
            }
        },
        Required = new[] { "sentiment", "confidence" }
    })
});

Or use simple JSON object mode:

var response = await client.V1.Chat.CreateCompletionAsync(new CreateCompletionRequest
{
    Model = Models.Gpt55,
    Messages = [new UserMessage("Return a JSON object with weather data.")],
    ResponseFormat = ResponseFormat.JsonObject
});

Function Calling & Tools

Use tools to extend the model's capabilities:

var response = await client.V1.Chat.CreateCompletionAsync(new CreateCompletionRequest
{
    Model = Models.Gpt55,
    Messages = [new UserMessage("What's the weather like in San Francisco?")],
    Tools = [
        new Tool
        {
            Type = ToolTypes.Function,
            Function = new Function
            {
                Name = "get_weather",
                Description = "Get current weather for a location",
                Parameters = new JsonSchema
                {
                    Type = "object",
                    Properties = new Dictionary<string, JsonSchema>
                    {
                        ["location"] = new JsonSchema
                        {
                            Type = "string",
                            Description = "The city and state"
                        }
                    },
                    Required = new[] { "location" }
                }
            }
        }
    ]
});

// Handle tool calls
if (response.Choices[0].Message is AssistantMessage assistantMsg && 
    assistantMsg.ToolCalls?.Length > 0)
{
    var toolCall = assistantMsg.ToolCalls[0];
    var weatherData = GetWeather(toolCall.Function.Arguments); // Your implementation
    
    // Continue conversation with tool response
    var followUp = await client.V1.Chat.CreateCompletionAsync(new CreateCompletionRequest
    {
        Model = Models.Gpt55,
        Messages = [
            new UserMessage("What's the weather like in San Francisco?"),
            assistantMsg,
            new ToolMessage(weatherData, toolCall.Id)
        ]
    });
}

Responses API

Use OpenAI's unified Responses API for enhanced capabilities:

var response = await client.V1.ResponsesClient.CreateResponseAsync(new CreateResponseRequest
{
    Model = Universal.OpenAI.Client.V1.Responses.Models.Gpt55,
    Input = "Tell me about the latest developments in AI."
});

if (response.Output.First() is MessageOutput messageOutput)
{
    var textContent = messageOutput.Content.OfType<OutputTextContent>().First();
    Console.WriteLine(textContent.Text);
}

Embeddings

Generate text embeddings:

var embeddings = await client.V1.Embeddings.CreateEmbeddingsAsync(new CreateEmbeddingsRequest
{
    Model = Universal.OpenAI.Client.V1.Embeddings.Models.TextEmbedding3Small,
    Input = "The quick brown fox jumps over the lazy dog."
});

Image Generation

Create images from text prompts:

var images = await client.V1.ImagesClient.CreateImageAsync(new CreateImageRequest
{
    Model = Universal.OpenAI.Client.V1.Images.Models.GptImage2,
    Prompt = "A sunset over the mountains",
    Size = "1024x1024"
});

gpt-image-* models always return base64-encoded image data on response.Data[i].B64Json.

Error Handling

The library throws HttpException for API errors:

try
{
    var response = await client.V1.Chat.CreateCompletionAsync(request);
}
catch (HttpException ex)
{
    Console.WriteLine($"API Error: {ex.StatusCode} - {ex.Message}");
}

Disposal

The client implements IDisposable:

using var client = new OpenAIClient("your-api-key");
// Client will be automatically disposed

Advanced Usage

Raw Streaming Response

using var httpResponse = await client.V1.Chat.CreateCompletionStreamingRawAsync(request);
// Forward the raw HTTP response stream

Specific Clients

using var chatClient = new ChatClient(apiKey);