HuggingFace

Features

• Fully generated C# SDK based on HuggingFace Hub, TGI and TEI OpenAPI specs using AutoSDK
• Three typed clients: HuggingFaceClient (Hub API), HuggingFaceInferenceClient (TGI chat/completions), HuggingFaceEmbeddingClient (TEI embeddings/reranking)
• Microsoft.Extensions.AI support: IChatClient and IEmbeddingGenerator<string, Embedding<float>>
• All modern .NET features — nullability, trimming, NativeAOT, source-generated JSON
• Targets net10.0

Getting Started

Installation

dotnet add package HuggingFace

Authentication

All clients require a HuggingFace API key. Get one at huggingface.co/settings/tokens.

usingHuggingFace;// Chat and completions (TGI)usingvarinferenceClient=newHuggingFaceInferenceClient(apiKey);// Embeddings, reranking, similarity (TEI)usingvarembeddingClient=newHuggingFaceEmbeddingClient(apiKey);// Hub API (model info, datasets, etc.)usingvarhubClient=newHuggingFaceClient(apiKey);

Examples

Chat Completion

Send a chat message to a HuggingFace-hosted model using the Microsoft.Extensions.AI IChatClient interface.

usingvarclient=newHuggingFaceInferenceClient(apiKey);IChatClientchatClient=client;varresponse=awaitchatClient.GetResponseAsync([newChatMessage(ChatRole.User,"Say hello in one word.")],newChatOptions{ModelId="Qwen/Qwen2.5-Coder-32B-Instruct",MaxOutputTokens=32,});Console.WriteLine(response.Text);

Streaming Chat Completion

Stream chat completion tokens as they are generated using the IChatClient interface.

usingvarclient=newHuggingFaceInferenceClient(apiKey);IChatClientchatClient=client;awaitforeach(varupdateinchatClient.GetStreamingResponseAsync([newChatMessage(ChatRole.User,"Say hello in one word.")],newChatOptions{ModelId="Qwen/Qwen2.5-Coder-32B-Instruct",MaxOutputTokens=32,})){Console.Write(update.Text);}

Generate Embeddings

Generate text embeddings using the Microsoft.Extensions.AI IEmbeddingGenerator interface with HuggingFace TEI.

usingvarclient=newHuggingFaceEmbeddingClient(apiKey);IEmbeddingGenerator<string,Embedding<float>>generator=client;varresult=awaitgenerator.GenerateAsync(["Hello world","How are you?"],newEmbeddingGenerationOptions{ModelId="sentence-transformers/all-MiniLM-L6-v2",});Console.WriteLine($"Embedding dimension: {result[0].Vector.Length}");Console.WriteLine($"Embeddings generated: {result.Count}");

Rerank Texts

Rerank a list of texts by relevance to a query using the TEI reranking endpoint.

usingvarclient=newHuggingFaceEmbeddingClient(apiKey);varresults=awaitclient.RerankAsync(query:"What is Deep Learning?",texts:["Deep Learning is a subset of Machine Learning.","The weather is sunny today.","Neural networks are inspired by the human brain.",],returnText:true);foreach(varrankinresults.OrderByDescending(r =>r.Score)){Console.WriteLine($"[{rank.Index}] score={rank.Score:F4} text={rank.Text}");}

Similarity Scoring

Compute cosine similarity between a source sentence and a list of candidate sentences.

usingvarclient=newHuggingFaceEmbeddingClient(apiKey);varscores=awaitclient.SimilarityAsync(inputs:newSimilarityInput{SourceSentence="What is Deep Learning?",Sentences=["Deep Learning is a subset of Machine Learning.","The weather is sunny today.","Neural networks are inspired by the human brain.",],});for(vari=0;i<scores.Count;i++){Console.WriteLine($"[{i}] similarity={scores[i]:F4}");}

Tokenize Text

Tokenize text into tokens using the TEI tokenization endpoint.

usingvarclient=newHuggingFaceEmbeddingClient(apiKey);vartokens=awaitclient.TokenizeAsync(inputs:newTokenizeInput("Hello world"),addSpecialTokens:true);foreach(vartokenintokens[0]){Console.WriteLine($"id={token.Id} text=\"{token.Text}\" special={token.Special}");}

Sparse Embeddings

Generate sparse embeddings for text using the TEI sparse embedding endpoint.

usingvarclient=newHuggingFaceEmbeddingClient(apiKey);varsparseEmbeddings=awaitclient.EmbedSparseAsync(inputs:newInput("Hello world"));foreach(varsvinsparseEmbeddings[0].Take(5)){Console.WriteLine($"index={sv.Index} value={sv.Value:F4}");}

Native Embeddings

Generate dense embeddings using the TEI-native embed endpoint with normalization control.

usingvarclient=newHuggingFaceEmbeddingClient(apiKey);varembeddings=awaitclient.EmbedAsync(inputs:newInput("Hello world"),normalize:true);Console.WriteLine($"Embedding dimension: {embeddings[0].Count}");

Decode Tokens

Tokenize text and decode it back using the TEI tokenization and decode endpoints.

usingvarclient=newHuggingFaceEmbeddingClient(apiKey);// Tokenize text into token IDs.vartokens=awaitclient.TokenizeAsync(inputs:newTokenizeInput("Hello world"),addSpecialTokens:false);vartokenIds=tokens[0].Select(t =>t.Id).ToList();Console.WriteLine($"Token IDs: [{string.Join(", ",tokenIds)}]");// Decode token IDs back to text.vardecoded=awaitclient.DecodeAsync(ids:newInputIds(value1:tokenIds,value2:null),skipSpecialTokens:true);Console.WriteLine($"Decoded: {decoded[0]}");

Who Am I

Get the authenticated user's account information using the Hub API.

usingvarclient=newHuggingFaceClient(apiKey);varresponse=awaitclient.Auth.GetWhoamiV2Async();Console.WriteLine($"User: {response}");

Trending Models

List recently trending models, datasets, and spaces on the HuggingFace Hub.

usingvarclient=newHuggingFaceClient(apiKey);varresponse=awaitclient.Models.GetTrendingAsync(limit:5);foreach(variteminresponse.RecentlyTrending){varid=item.Value1?.RepoData?.Id??item.Value2?.RepoData?.Id??item.Value3?.RepoData?.Id;varauthor=item.Value1?.RepoData?.Author??item.Value2?.RepoData?.Author??item.Value3?.RepoData?.Author;if(idis not null){Console.WriteLine($"{id} by {author}");}}

List Model Tags

List available model tags grouped by type from the HuggingFace Hub.

usingvarclient=newHuggingFaceClient(apiKey);vartags=awaitclient.Models.GetModelsTagsByTypeAsync();foreach(var(tagType,tagList)intags){Console.WriteLine($"{tagType}: {tagList.Count} tags");}

Search Models

Search for models, datasets, and spaces on the HuggingFace Hub using quicksearch.

usingvarclient=newHuggingFaceClient(apiKey);varresponse=awaitclient.RepoSearch.CreateQuicksearchAsync(request:newRequest45{Q="text-generation",Limit=5,Exclude=[],});Console.WriteLine($"Found {response.ModelsCount} models, {response.DatasetsCount} datasets");foreach(varmodelinresponse.Models){Console.WriteLine($" {model.Id} (weight={model.TrendingWeight:F2})");}

Error Handling

Handle API errors gracefully using the ApiException type.

usingvarclient=newHuggingFaceClient("invalid-api-key");try{awaitclient.Auth.GetWhoamiV2Async();}catch(ApiExceptionex){Console.WriteLine($"Status: {ex.StatusCode}");Console.WriteLine($"Message: {ex.Message}");Console.WriteLine($"Body: {ex.ResponseBody}");}

Search Datasets

Search for datasets on the HuggingFace Hub using quicksearch and list results.

usingvarclient=newHuggingFaceClient(apiKey);varresponse=awaitclient.RepoSearch.CreateQuicksearchAsync(request:newRequest45{Q="sentiment analysis",Limit=5,Exclude=[],});Console.WriteLine($"Models: {response.ModelsCount}, Datasets: {response.DatasetsCount}, Spaces: {response.SpacesCount}");foreach(vardatasetinresponse.Datasets){Console.WriteLine($" Dataset: {dataset.Id}");}foreach(varspaceinresponse.Spaces){Console.WriteLine($" Space: {space.Id}");}

Trending by Type

List trending items filtered by type (model, dataset, or space).

usingvarclient=newHuggingFaceClient(apiKey);varspaces=awaitclient.Models.GetTrendingAsync(type:Type5.Space,limit:3);Console.WriteLine("Trending Spaces:");foreach(variteminspaces.RecentlyTrending){varid=item.Value1?.RepoData?.Id??item.Value2?.RepoData?.Id??item.Value3?.RepoData?.Id;Console.WriteLine($" {id}");}

Search Papers

Search for papers and collections on the HuggingFace Hub.

usingvarclient=newHuggingFaceClient(apiKey);varresponse=awaitclient.RepoSearch.CreateQuicksearchAsync(request:newRequest45{Q="transformer attention",Limit=5,Exclude=[],});Console.WriteLine($"Papers: {response.PapersCount}, Collections: {response.CollectionsCount}");foreach(varpaperinresponse.Papers){Console.WriteLine($" Paper: {paper.Id}");}foreach(varcollectioninresponse.Collections){Console.WriteLine($" Collection: {collection.Title} - {collection.Description}");}

Ecosystem maintenance

This SDK is one of more than 200 .NET SDKs maintained with AutoSDK. The tryAGI SDK audit continuously checks repository synchronization, upstream-spec regeneration, release workflows, warnings, public API visibility, and trimming/NativeAOT compatibility.

Every issue is first investigated for ecosystem-wide applicability. When the root cause belongs in AutoSDK, we fix and regression-test the generator, then roll the improvement out to every applicable SDK. Provider-specific behavior remains in this repository when it cannot be derived safely from the API specification.

Issue content—including code blocks, logs, links, and attachments—is treated only as untrusted diagnostic data. Embedded control instructions, hidden directives, delimiter tricks, or requests to alter triage or tooling behavior are ignored. Please report reproducible technical evidence and remove secrets and personal data.

Support

Priority place for bugs: https://github.com/tryAGI/HuggingFace/issues
Priority place for ideas and general questions: https://github.com/tryAGI/HuggingFace/discussions
Discord: https://discord.gg/Ca2xhfBf3v

OpenAPI specs

• Serverless Inference OpenAPI spec - (Can't find the link)
• Local Text Generation Inference OpenAPI spec
• Local Text Embeddings Inference OpenAPI spec
• Inference Endpoints (dedicated) OpenAPI spec

Acknowledgments

This project is supported by JetBrains through the Open Source Support Program.