C# / .NET: HTML/CSS to Image

Generate png, jpg or webp images with C# and .NET. Renders exactly like Google Chrome.

Official .NET Package

We provide an official NuGet package for .NET that makes it easy to generate images from HTML/CSS in your .NET applications.

Package	NuGet	Description
HtmlCssToImage		Core client library for the HTML/CSS to Image API
HtmlCssToImage.DependencyInjection		ASP.NET Core dependency injection
HtmlCssToImage.Blazor		Open Graph image tags for Blazor
HtmlCssToImage.TagHelpers		Tag helpers for Razor Pages and MVC

For full documentation, see the GitHub repository.

Quick Start

1. Install the NuGet package

dotnet add package HtmlCssToImage

Or using the Package Manager Console:

Install-Package HtmlCssToImage

2. Create a client

using HtmlCssToImage;

// Retrieve your User ID and API Key from https://htmlcsstoimage.com/dashboard
var client = new HtmlCssToImageClient("your-user-id", "your-api-key");

3. Generate an image

var request = new CreateHtmlCssImageRequest
{
    Html = "<div class='box'>Hello, World!</div>",
    Css = ".box { padding: 20px; background: #03B875; color: white; font-family: 'Roboto'; }",
    GoogleFonts = "Roboto"
};

using var result = await client.CreateImageAsync(request);

if (result.Success)
{
    Console.WriteLine($"Image URL: {result.Response.Url}");
    // https://hcti.io/v1/image/be4c5118-fe19-462b-a49e-48cf72697a9d
}

API calls return an ApiResult<T> that owns the raw HttpResponseMessage. The raw response lets you inspect headers, the originating request, and other HTTP details when needed. Use using or using var so it is disposed after you finish reading the result.

Creating Images from a URL

Capture a screenshot of any webpage:

var request = new CreateUrlImageRequest
{
    Url = "https://htmlcsstoimage.com",
    FullScreen = true  // Capture the full scrollable page
};

using var result = await client.CreateImageAsync(request);

if (result.Success)
{
    Console.WriteLine($"Screenshot URL: {result.Response.Url}");
}

Using Templates

Generate images from pre-defined templates with dynamic values:

var request = new CreateTemplatedImageRequest
{
    TemplateId = "your-template-id",
    TemplateValues = new Dictionary<string, string>
    {
        { "title", "Welcome!" },
        { "subtitle", "This is a templated image" }
    }
};

using var result = await client.CreateImageAsync(request);

ASP.NET Core Integration

For ASP.NET Core applications, use the HtmlCssToImage.DependencyInjection package for seamless integration:

dotnet add package HtmlCssToImage.DependencyInjection

Configure in Program.cs:

builder.Services.AddHtmlCssToImage(options =>
{
    options.UserId = "your-user-id";
    options.ApiKey = "your-api-key";
});

Inject and use in your services:

public class ImageService
{
    private readonly IHtmlCssToImageClient _client;

    public ImageService(IHtmlCssToImageClient client)
    {
        _client = client;
    }

    public async Task<string> GenerateImageAsync(string html, string css)
    {
        var request = new CreateHtmlCssImageRequest { Html = html, Css = css };
        using var result = await _client.CreateImageAsync(request);
        return result.Success ? result.Response.Url : null;
    }
}

Blazor Integration

For Blazor applications, use the HtmlCssToImage.Blazor package to easily generate Open Graph image tags:

dotnet add package HtmlCssToImage.Blazor

Razor Pages / MVC Tag Helpers

For ASP.NET Core Razor Pages and MVC applications, use the HtmlCssToImage.TagHelpers package:

dotnet add package HtmlCssToImage.TagHelpers

Batch Image Creation

Create multiple images in a single API call:

var variations = new List<CreateHtmlCssImageRequest>
{
    new() { Html = "<div>Image 1</div>", Css = "div { color: red; }" },
    new() { Html = "<div>Image 2</div>", Css = "div { color: blue; }" },
    new() { Html = "<div>Image 3</div>", Css = "div { color: green; }" }
};

using var result = await client.CreateImageBatchAsync(variations);

if (result.Success)
{
    foreach (var image in result.Response)
    {
        Console.WriteLine($"Image URL: {image.Url}");
    }
}

Signed URLs (Create and Render)

Generate signed URLs without making an API call. The image is rendered on-demand when the URL is accessed:

// Generate a signed URL synchronously (no API call)
var url = client.CreateAndRenderUrl(new CreateHtmlCssImageRequest
{
    Html = "<div>Hello!</div>",
    Css = "div { padding: 20px; }"
});

Console.WriteLine($"Signed URL: {url}");
// Use this URL in img tags - the image renders when accessed

This is useful when you have content that may never be viewed, allowing you to generate images on-demand without using API credits upfront.

Performance & Native AOT

The official .NET client is built with performance in mind and fully supports Native AOT (Ahead-of-Time) compilation in .NET 9+. The client uses source-generated JSON serialization internally.

Plain HTTP Example

If you prefer not to use the NuGet package, you can make HTTP requests directly:

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();

// Set up Basic Authentication
var credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes("user_id:api_key"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = new
{
    html = "<div class='box'>Hello, world!</div>",
    css = ".box { padding: 20px; background-color: #03B875; color: white; }"
};

using var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

using var response = await client.PostAsync("https://hcti.io/v1/image", content);
var json = await response.Content.ReadAsStringAsync();

Console.WriteLine(json);
// {"url":"https://hcti.io/v1/image/be4c5118-fe19-462b-a49e-48cf72697a9d"}

Legacy WebClient Example

For older .NET Framework projects:

using System.Net;

byte[] result;
string html = "<div class='ping'>Pong ✅</div>";
string css = ".ping {padding: 20px; font-family:'sans-serif'; }";

using (var client = new WebClient())
{
    string credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes("user_id:api_key"));
    client.Headers[HttpRequestHeader.Authorization] = "Basic " + credentials;

    result = client.UploadValues(
        "https://hcti.io/v1/image",
        "POST", 
        new System.Collections.Specialized.NameValueCollection()
        {
            { "html", html }, { "css", css }
        }
    );
}

string resultString = System.Text.Encoding.UTF8.GetString(result);
Console.WriteLine(resultString);
// {"url":"https://hcti.io/v1/image/404ed70d-dcb9-4778-9be4-fad912321d5b"}

Need help?

We’re always looking to improve this documentation. Please send us an email: support@htmlcsstoimage.com. We respond fast.