.NET SDK

Runnable versions of every example on this page live in nexos-ai/dotnet-examples.

Setup

Install the packages:

dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI
dotnet add package DotNetEnv

All examples read the API key from a .env file:

API_KEY=YOUR_NEXOS_API_KEY

OpenAI-compatible clients use the base URL https://api.nexos.ai/v1; the Anthropic Messages API takes the bare https://api.nexos.ai because the SDK appends /v1/messages itself.

Model IDs on nexos.ai are the model names shown in the console (e.g. GPT 5.5, Claude Sonnet 5, Whisper). List them with GET /v1/models.

The examples below use Microsoft.Extensions.AI — the provider-neutral abstraction layer — over an OpenAIClient pointed at the gateway. Where a capability has no Microsoft.Extensions.AI surface, the raw OpenAI SDK client is used directly.

Chat Completion

Send a conversation and get the model's next reply — the standard OpenAI-compatible endpoint, supported by most chat models on the platform.

using DotNetEnv;
using Microsoft.Extensions.AI;
using OpenAI;
using System.ClientModel;

Env.TraversePath().Load();
var apiKey = Environment.GetEnvironmentVariable("API_KEY")!;

var options = new OpenAIClientOptions { Endpoint = new Uri("https://api.nexos.ai/v1") };

IChatClient chatClient = new OpenAIClient(new ApiKeyCredential(apiKey), options)
    .GetChatClient("GPT 5.5")
    .AsIChatClient();

var response = await chatClient.GetResponseAsync(
    "how many letters 'r' in the word 'strawberry'");

Console.WriteLine(response.Text);

Chat Completion with history

Keep the full message list between turns so the model can resolve references to earlier context.

List<ChatMessage> messages =
[
    new(ChatRole.System, "You are a meticulous linguist who counts letters in words."),
    new(ChatRole.User, "how many letters 'r' in the word 'strawberry'"),
];

var first = await chatClient.GetResponseAsync(messages);
Console.WriteLine(first.Text);

messages.AddMessages(first);
messages.Add(new ChatMessage(ChatRole.User, "and how many 'b'?"));

var second = await chatClient.GetResponseAsync(messages);
Console.WriteLine(second.Text);

Streaming

Receive the reply incrementally as server-sent events instead of waiting for the whole message — useful for chat UIs and long outputs.

await foreach (var update in chatClient.GetStreamingResponseAsync(
    "how many letters 'r' in the word 'strawberry'"))
{
    Console.Write(update.Text);
}

Console.WriteLine();

Reasoning

Let the model reason internally before answering — the response carries reasoning content alongside the final text. Reasoning effort is an experimental surface in the OpenAI SDK, so the OPENAI001 diagnostic is suppressed.

#pragma warning disable OPENAI001

using Microsoft.Extensions.AI;
using OpenAI.Chat;

var chatOptions = new ChatOptions
{
    RawRepresentationFactory = _ => new ChatCompletionOptions
    {
        ReasoningEffortLevel = ChatReasoningEffortLevel.Medium,
    },
};

var response = await chatClient.GetResponseAsync(
    "how many letters 'r' in the word 'strawberry'",
    chatOptions);

foreach (var content in response.Messages.SelectMany(m => m.Contents))
{
    if (content is TextReasoningContent reasoning)
    {
        Console.WriteLine($"[thinking] {reasoning.Text}");
    }
    else if (content is TextContent text)
    {
        Console.WriteLine(text.Text);
    }
}

#pragma warning restore OPENAI001

Function calling

Let the model call functions you define. With FunctionInvokingChatClient in the pipeline, the round trip is automatic: the model requests the tool, the client runs your delegate, sends the result back, and returns the final answer.

using Microsoft.Extensions.AI;

[Description("Count occurrences of a letter in a word")]
static int CountLetters(string word, string letter) =>
    word.Count(c => c.ToString().Equals(letter, StringComparison.OrdinalIgnoreCase));

IChatClient chatClient = new OpenAIClient(new ApiKeyCredential(apiKey), options)
    .GetChatClient("GPT 5.5")
    .AsIChatClient()
    .AsBuilder()
    .UseFunctionInvocation()
    .Build();

var chatOptions = new ChatOptions
{
    Tools = [AIFunctionFactory.Create(CountLetters)],
};

var response = await chatClient.GetResponseAsync(
    "Use the count_letters tool to count letters 'r' in the word 'strawberry'",
    chatOptions);

Console.WriteLine(response.Text);

Caching

Wrap the client in DistributedCachingChatClient to serve identical requests from a local cache instead of calling the gateway again — the second call below returns without a network round trip.

using Microsoft.Extensions.AI;
using Microsoft.Extensions.Caching.Distributed;
using Microsoft.Extensions.Caching.Memory;
using Microsoft.Extensions.Options;

IDistributedCache cache = new MemoryDistributedCache(
    Options.Create(new MemoryDistributedCacheOptions()));

IChatClient chatClient = new OpenAIClient(new ApiKeyCredential(apiKey), options)
    .GetChatClient("GPT 5.5")
    .AsIChatClient()
    .AsBuilder()
    .UseDistributedCache(cache)
    .Build();

const string prompt = "how many letters 'r' in the word 'strawberry'";

var first = await chatClient.GetResponseAsync(prompt);   // hits the gateway
var second = await chatClient.GetResponseAsync(prompt);  // served from cache

Console.WriteLine(first.Text);
Console.WriteLine(second.Text);

Structured output

Ask for the answer as a typed .NET object. The client derives a JSON schema from the record, sends it as the response format, and deserializes the reply.

using Microsoft.Extensions.AI;

record LetterCount(string Word, string Letter, int Count);

var response = await chatClient.GetResponseAsync<LetterCount>(
    "how many letters 'r' in the word 'strawberry'");

var result = response.Result;
Console.WriteLine($"{result.Letter} appears {result.Count} times in {result.Word}");

Embedding

Convert text into a numeric vector for semantic search, clustering, and RAG. One vector is returned per input.

using Microsoft.Extensions.AI;
using OpenAI;
using System.ClientModel;

var options = new OpenAIClientOptions { Endpoint = new Uri("https://api.nexos.ai/v1") };

IEmbeddingGenerator<string, Embedding<float>> generator =
    new OpenAIClient(new ApiKeyCredential(apiKey), options)
        .GetEmbeddingClient("Text Embedding 3 Large")
        .AsIEmbeddingGenerator();

var embedding = await generator.GenerateVectorAsync(
    "There are three letters 'r' in the word 'strawberry'.");

Console.WriteLine($"dimensions: {embedding.Length}");
Console.WriteLine($"first values: {string.Join(", ", embedding.ToArray().Take(5))}");

Image Generation

Generate an image from a text prompt. IImageGenerator is experimental in Microsoft.Extensions.AI.Abstractions, so the MEAI001 diagnostic is suppressed.

#pragma warning disable MEAI001

using Microsoft.Extensions.AI;

IImageGenerator imageGenerator = new OpenAIClient(new ApiKeyCredential(apiKey), options)
    .GetImageClient("GPT Image 2")
    .AsIImageGenerator();

var response = await imageGenerator.GenerateImagesAsync(
    "three letters 'r' with strawberry texture");

foreach (var content in response.Contents)
{
    if (content is UriContent uri)
    {
        Console.WriteLine(uri.Uri);
    }
    else if (content is DataContent data)
    {
        await File.WriteAllBytesAsync("generated.png", data.Data.ToArray());
        Console.WriteLine("saved to generated.png");
    }
}

#pragma warning restore MEAI001

Audio Generation

Convert text to spoken audio (text-to-speech).

using OpenAI;
using OpenAI.Audio;
using System.ClientModel;

var options = new OpenAIClientOptions { Endpoint = new Uri("https://api.nexos.ai/v1") };
var audioClient = new OpenAIClient(new ApiKeyCredential(apiKey), options)
    .GetAudioClient("tts-1");

BinaryData speech = await audioClient.GenerateSpeechAsync(
    "There are three letters 'r' in the word 'strawberry'.",
    GeneratedSpeechVoice.Alloy);

await File.WriteAllBytesAsync("generated.mp3", speech.ToArray());

Audio Transcription

Transcribe an audio file to text in its original language. The example reads sound.mp3 — you can create one with the Audio Generation example above.

using OpenAI.Audio;

var audioClient = new OpenAIClient(new ApiKeyCredential(apiKey), options)
    .GetAudioClient("Whisper");

var transcription = await audioClient.TranscribeAudioAsync("sound.mp3");

Console.WriteLine(transcription.Value.Text);

Audio Translation

Transcribe an audio file and translate the text into English. The example reads sound.mp3 — you can create one with the Audio Generation example above.

using OpenAI.Audio;

var audioClient = new OpenAIClient(new ApiKeyCredential(apiKey), options)
    .GetAudioClient("Whisper");

var translation = await audioClient.TranslateAudioAsync("sound.mp3");

Console.WriteLine(translation.Value.Text);

Dependency injection

In ASP.NET Core, register IChatClient once and inject it wherever it's needed. The key comes from configuration — user secrets, an environment variable, or appsettings.Development.json.

using Microsoft.Extensions.AI;
using OpenAI;
using System.ClientModel;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddChatClient(sp =>
{
    var apiKey = sp.GetRequiredService<IConfiguration>()["API_KEY"]!;
    var options = new OpenAIClientOptions { Endpoint = new Uri("https://api.nexos.ai/v1") };

    return new OpenAIClient(new ApiKeyCredential(apiKey), options)
        .GetChatClient("GPT 5.5")
        .AsIChatClient();
})
.UseFunctionInvocation()
.UseLogging();

var app = builder.Build();

app.MapPost("/chat", async (ChatRequest request, IChatClient chatClient) =>
{
    var response = await chatClient.GetResponseAsync(request.Message);
    return Results.Ok(new { reply = response.Text });
});

app.Run();

record ChatRequest(string Message);

Set the key and call the endpoint:

dotnet user-secrets set API_KEY "YOUR_NEXOS_API_KEY"
dotnet run

curl -X POST http://localhost:5000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "how many letters r in the word strawberry"}'

Anthropic Messages API

The /v1/messages endpoint implements the Anthropic Messages API — including cache_control prompt caching, thinking blocks, and tool_use — and is available for models that list the messages endpoint in GET /v1/models (e.g. Claude models).

There is no Microsoft-owned provider for it. Use the community Anthropic.SDK package against the bare base URL https://api.nexos.ai, or call the endpoint with a plain HttpClient.

using Anthropic.SDK;
using Anthropic.SDK.Messaging;

// The Anthropic SDK appends /v1/messages itself, so the base URL must not include /v1
var anthropic = new AnthropicClient(new APIAuthentication(apiKey))
{
    ApiUrlFormat = "https://api.nexos.ai/{0}/{1}",
};

var response = await anthropic.Messages.GetClaudeMessageAsync(new MessageParameters
{
    Model = "Claude Sonnet 5",
    MaxTokens = 1024,
    Messages =
    [
        new Message(RoleType.User, "how many letters 'r' in the word 'strawberry'"),
    ],
});

Console.WriteLine(response.Message);