#.NET SDK

The Pixault .NET SDK provides a fluent API for image URL construction, uploads, and management. Available as Pixault.Client on NuGet.

Source on GitHub

#Installation

dotnet add package Pixault.Client
                              

#Configuration

#ASP.NET Core (Dependency Injection)

builder.Services.AddPixault(options =>
{
    options.BaseUrl = "https://img.pixault.io";
    options.DefaultProject = "myapp";
    options.ClientId = "px_cl_your_client_id";
    options.ClientSecret = "pk_your_secret_key";
});
                              

#Manual Instantiation

var options = new PixaultOptions
{
    BaseUrl = "https://img.pixault.io",
    DefaultProject = "myapp",
    ClientId = "px_cl_your_client_id",
    ClientSecret = "pk_your_secret_key",
};
var imageService = new PixaultImageService(options);
var uploadClient = new PixaultUploadClient(httpClient, options);
var adminClient = new PixaultAdminClient(httpClient, options);
                              

#URL Builder

The fluent URL builder generates transform URLs without making HTTP requests. Start with .For(...), passing either a publicId (a human-readable slug) or a legacy imageId — the builder emits the correct URL grammar for each:

// Inject PixaultImageService. Uses the configured DefaultProject:
var url = imageService.For("sunset-over-tahoe")
    .Width(800)
    .Height(600)
    .Fit(FitMode.Cover)
    .Quality(85)
    .Format("webp")
    .Build();
// → "https://img.pixault.io/myapp/w_800,h_600,fit_cover,q_85/sunset-over-tahoe.webp"
// Pass an explicit project:
var url = imageService.For("myapp", "sunset-over-tahoe").Width(400).Build();
// → "https://img.pixault.io/myapp/w_400/sunset-over-tahoe.auto"
                              

The output format defaults to auto (Accept-header negotiation) — call .Format(...) only to pin a specific format.

#publicId vs. imageId grammar

.For(...) accepts either identifier and picks the matching URL shape automatically — an argument that starts with img_, vid_, or eps_ is treated as a legacy imageId, anything else as a publicId:

// publicId → transforms first (Cloudinary order)
imageService.For("sunset-over-tahoe").Width(800).Build();
// → "https://img.pixault.io/myapp/w_800/sunset-over-tahoe.auto"
// imageId → id first (legacy grammar, unchanged)
imageService.For("img_01JKXYZ").Width(800).Build();
// → "https://img.pixault.io/myapp/img_01JKXYZ/w_800.auto"
                              

See Image Delivery — Delivery by publicId for the URL grammar in full.

#Available Methods

#Named Transforms

var url = imageService.For("sunset-over-tahoe")
    .Transform("thumbnail")
    .Format("webp")
    .Build();
                              

#LQIP Placeholder

var placeholder = imageService.For("sunset-over-tahoe")
    .Width(40).Quality(20).Blur(10)
    .Format("webp")
    .Build();
                              

#Upload Client

// From file stream
await using var stream = File.OpenRead("photo.jpg");
var result = await uploadClient.UploadAsync(
    stream,
    "photo.jpg",
    alt: "Team photo",
    tags: ["team", "2025"]);
Console.WriteLine($"Uploaded: {result.Id}");
Console.WriteLine($"URL: {result.Url}");
                              

#Admin Client

// List images
var response = await adminClient.ListImagesAsync(limit: 20, tag: "nature");
foreach (var image in response.Images)
{
    Console.WriteLine($"{image.Id}: {image.Alt}");
}
// Get metadata
var metadata = await adminClient.GetImageAsync("img_01JKXYZ");
// Update metadata
await adminClient.UpdateImageAsync("img_01JKXYZ", new
{
    alt = "Updated description",
    tags = new[] { "updated", "tags" }
});
// Delete
await adminClient.DeleteImageAsync("img_01JKXYZ");
// Named transforms
var transforms = await adminClient.ListTransformsAsync();
await adminClient.CreateTransformAsync("thumb", new
{
    parameters = new { w = 200, h = 200, fit = "cover" },
    locked = new[] { "w", "h" }
});
                              

#List & Search Images

// List all images
var result = await admin.ListImagesAsync(project: "my-project");
// Search by text
var matches = await admin.ListImagesAsync(project: "my-project", search: "hero");
// Filter by category
var tattoos = await admin.ListImagesAsync(project: "my-project", category: "tattoo-flash");
// Paginate
var page2 = await admin.ListImagesAsync(cursor: result.NextCursor, project: "my-project");
                              

#Watermarks

Manage watermark images at the project level. Watermarks are PNG (or other image) files stored separately from your image library and applied to images at delivery time.

// List all watermarks for a project
var watermarks = await admin.ListWatermarksAsync(project: "my-project");
foreach (var wm in watermarks)
{
    Console.WriteLine($"{wm.Id} ({wm.SizeBytes} bytes)");
}
// Upload (or replace) a watermark
await using var stream = File.OpenRead("logo.png");
var wm = await admin.UploadWatermarkAsync(
    watermarkId: "logo",
    imageStream: stream,
    contentType: "image/png",
    project: "my-project");
// Delete a watermark
await admin.DeleteWatermarkAsync("logo", project: "my-project");
                              

#Apply a watermark to a URL

var url = imageService.For("img_01JKXYZ")
    .Width(1200)
    .Watermark("logo", WmPosition.BottomRight, opacity: 40)
    .Format("jpg")
    .Build();
// → "...img_01JKXYZ/w_1200,wm_logo,wm_pos_br,wm_opacity_40.jpg"
                              

#Position values

#Bake a watermark into a Named Transform

You can lock a watermark into a named transform so every URL using that preset gets the watermark automatically:

await admin.SaveTransformAsync("branded", new NamedTransformSave
{
    Width = 1200,
    Quality = 85,
    WatermarkId = "logo",
    WatermarkPosition = "br",
    WatermarkOpacity = 40,
    LockedParameters = ["wm", "wm_pos", "wm_opacity"],
});
                              

Locked parameters cannot be overridden via URL parameters.

#Folder Management

// List folders
var folders = await client.ListFoldersAsync();
// Create a folder
await client.CreateFolderAsync("portfolio/landscapes");
// Delete a folder
await client.DeleteFolderAsync("portfolio/landscapes");
// List images in a specific folder
var result = await client.ListImagesAsync(folder: "portfolio/landscapes");
                              

#Blazor Integration

The Pixault.Blazor component library provides ready-to-use Blazor components. See the Blazor Integration Guide for details.

#Error Handling

The SDK throws PixaultApiException for HTTP errors:

try
{
    await uploadClient.UploadAsync(stream, "photo.jpg");
}
catch (PixaultApiException ex) when (ex.StatusCode == 413)
{
    Console.WriteLine("Storage quota exceeded");
}
catch (PixaultApiException ex) when (ex.StatusCode == 429)
{
    Console.WriteLine($"Rate limited. Retry after {ex.RetryAfter} seconds");
}