CivitaiSharp.Tools 0.9.0

CivitaiSharp

A modern, lightweight, and AOT-ready .NET 10 client library for all things Civitai.com.

Note: CivitaiSharp is currently in Alpha. APIs, features, and stability are subject to change.

Table of Contents

1. Packages and Release Schedule
2. Installation
3. Quick Start
4. Configuration
5. API Examples
6. Features
7. Documentation
8. Known API Quirks
9. Versioning
10. License
11. Contributing

1. Packages and Release Schedule

Note: All packages are currently in Alpha. APIs may change between minor versions.

Warning: CivitaiSharp.Sdk is not fully tested and should not be used in production environments. Use at your own risk.

2. Installation

Install via NuGet:

# Core library - API client for models, images, tags, and creators
dotnet add package CivitaiSharp.Core --prerelease

# SDK - Image generation and job management (requires API token)
dotnet add package CivitaiSharp.Sdk --prerelease

# Tools - File hashing, downloads, and HTML parsing
dotnet add package CivitaiSharp.Tools --prerelease

3. Quick Start

Minimal Example

The simplest way to get started with CivitaiSharp.Core:

using CivitaiSharp.Core;
using CivitaiSharp.Core.Extensions;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddCivitaiApi();

await using var provider = services.BuildServiceProvider();
var client = provider.GetRequiredService<IApiClient>();

var result = await client.Models.ExecuteAsync();
if (result.IsSuccess)
{
    foreach (var model in result.Value.Items)
        Console.WriteLine(model.Name);
}

Full Example with Configuration

using CivitaiSharp.Core;
using CivitaiSharp.Core.Extensions;
using CivitaiSharp.Core.Models;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddCivitaiApi(options =>
{
    options.TimeoutSeconds = 120;
    options.StrictJsonParsing = true;
});

await using var provider = services.BuildServiceProvider();
var client = provider.GetRequiredService<IApiClient>();

var result = await client.Models
    .WhereType(ModelType.Checkpoint)
    .WhereNsfw(false)
    .OrderBy(ModelSort.MostDownloaded)
    .ExecuteAsync(resultsLimit: 10);

if (result.IsSuccess)
{
    foreach (var model in result.Value.Items)
        Console.WriteLine($"{model.Name} by {model.Creator?.Username}");
}
else
{
    Console.WriteLine($"Error: {result.ErrorInfo.Message}");
}

4. Configuration

Using appsettings.json

CivitaiSharp.Core reads configuration from the CivitaiApi section by default.

Minimal Configuration (appsettings.json)

{
  "CivitaiApi": {
  }
}

All settings have sensible defaults, so an empty section is valid.

Full Configuration (appsettings.json)

{
  "CivitaiApi": {
    "BaseUrl": "https://civitai.com",
    "ApiVersion": "v1",
    "ApiKey": null,
    "TimeoutSeconds": 30,
    "StrictJsonParsing": false
  }
}

Authentication Note: The Core library can query public endpoints (models, images, tags, creators) without an API key. An API key is only required for authenticated features like favorites, hidden models, and higher rate limits. NSFW Content: Setting WhereNsfw(true) on models or using certain ImageNsfwLevel values (Mature, X) requires authentication. This is different from CivitaiSharp.Sdk which always requires an API token for all operations.

Configuration with IConfiguration

using CivitaiSharp.Core.Extensions;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var services = new ServiceCollection();
services.AddCivitaiApi(configuration);
// Or with a custom section name:
// services.AddCivitaiApi(configuration, "MyCustomSection");

await using var provider = services.BuildServiceProvider();

5. API Examples

CivitaiSharp.Core provides fluent builders for each endpoint. Each builder is immutable and thread-safe.

Models Endpoint

// Get all models (default query)
var result = await client.Models.ExecuteAsync();

// Get a specific model by ID
var result = await client.Models.GetByIdAsync(12345);
if (result.IsSuccess)
    Console.WriteLine($"Model: {result.Value.Name}");

// Get the first matching model (efficient single-item retrieval)
var result = await client.Models
    .WhereName("SDXL")
    .FirstOrDefaultAsync();
if (result is { IsSuccess: true, Value: not null })
    Console.WriteLine($"Found: {result.Value.Name}");

// Search by name
var result = await client.Models
    .WhereName("SDXL")
    .ExecuteAsync();

// Filter by type and sort
var result = await client.Models
    .WhereType(ModelType.Checkpoint)
    .OrderBy(ModelSort.MostDownloaded)
    .ExecuteAsync(resultsLimit: 25);

// Filter by tag
var result = await client.Models
    .WhereTag("anime")
    .WhereNsfw(false)
    .ExecuteAsync();

// Filter by creator
var result = await client.Models
    .WhereUsername("Mewyk")
    .OrderBy(ModelSort.Newest)
    .ExecuteAsync();

// Filter by base model (string value, e.g., "SDXL 1.0", "SD 1.5", "Flux.1 D")
var result = await client.Models
    .WhereBaseModel("SDXL 1.0")
    .WhereType(ModelType.Lora)
    .ExecuteAsync();

// Filter by multiple base models
var result = await client.Models
    .WhereBaseModels("SDXL 1.0", "Pony")
    .ExecuteAsync();

// Filter by specific model IDs (ignored if query is also provided)
var result = await client.Models
    .WhereIds(12345, 67890, 11111)
    .ExecuteAsync();

// Get a specific model version by version ID
var versionResult = await client.Models.GetByVersionIdAsync(130072);
if (versionResult.IsSuccess)
{
    Console.WriteLine($"Version: {versionResult.Value.Name}");
    Console.WriteLine($"AIR: {versionResult.Value.AirIdentifier}");
}

// Get a model version by file hash (SHA256, AutoV2, CRC32, etc.)
var hashResult = await client.Models.GetByVersionHashAsync("ABC123DEF456");
if (hashResult.IsSuccess)
{
    Console.WriteLine($"Found: {hashResult.Value.Model?.Name}");
    Console.WriteLine($"AIR: {hashResult.Value.AirIdentifier}");
}

Images Endpoint

// Get all images (default query)
var result = await client.Images.ExecuteAsync();

// Get the first matching image
var result = await client.Images
    .WhereModelId(12345)
    .FirstOrDefaultAsync();
if (result is { IsSuccess: true, Value: not null })
    Console.WriteLine($"Image URL: {result.Value.Url}");

// Filter by model ID
var result = await client.Images
    .WhereModelId(12345)
    .ExecuteAsync();

// Filter by model version ID
var result = await client.Images
    .WhereModelVersionId(67890)
    .OrderBy(ImageSort.Newest)
    .ExecuteAsync();

// Filter by username
var result = await client.Images
    .WhereUsername("Mewyk")
    .WhereNsfwLevel(ImageNsfwLevel.None)
    .ExecuteAsync(resultsLimit: 50);

// Filter by post ID
var result = await client.Images
    .WherePostId(11111)
    .ExecuteAsync();

Tags Endpoint

// Get all tags (default query)
var result = await client.Tags.ExecuteAsync();

// Search tags by name
var result = await client.Tags
    .WhereName("portrait")
    .ExecuteAsync(resultsLimit: 100);

Creators Endpoint

// Get all creators (default query)
var result = await client.Creators.ExecuteAsync();

// Search creators by name
var result = await client.Creators
    .WhereName("Mewyk")
    .ExecuteAsync(resultsLimit: 20);

// Page-based pagination (Models, Tags, and Creators use pages, not cursors)
var result = await client.Creators
    .WithPageIndex(2)
    .ExecuteAsync(resultsLimit: 50);

Pagination

// Cursor-based pagination (Images only)
string? cursor = null;
var allImages = new List<Image>();

do
{
    result = await client.Images
        .WhereModelId(12345)
        .ExecuteAsync(resultsLimit: 100, cursor: cursor);

    if (!result.IsSuccess)
        break;

    allImages.AddRange(result.Value.Items);
    cursor = result.Value.Metadata?.NextCursor;

} while (cursor is not null);

// Page-based pagination (Models, Tags, Creators)
var page1 = await client.Models.WithPageIndex(1).ExecuteAsync();
var page2 = await client.Tags.WithPageIndex(2).ExecuteAsync();
var page3 = await client.Creators.WithPageIndex(3).ExecuteAsync();

Tools - File Hashing

using CivitaiSharp.Tools.Hashing;
using CivitaiSharp.Tools.Extensions;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddCivitaiDownloads();

await using var provider = services.BuildServiceProvider();
var hashingService = provider.GetRequiredService<IFileHashingService>();

// Compute SHA256 hash
var result = await hashingService.ComputeHashAsync(
    @"C:\Models\model.safetensors",
    HashAlgorithm.Sha256);

if (result.IsSuccess)
{
    Console.WriteLine($"Hash: {result.Value.Hash}");
    Console.WriteLine($"Size: {result.Value.FileSize:N0} bytes");
}

// Supported algorithms: Sha256, Sha512, Blake3, Crc32
var blake3Result = await hashingService.ComputeHashAsync(filePath, HashAlgorithm.Blake3);

Tools - Downloading Files

using CivitaiSharp.Core;
using CivitaiSharp.Core.Extensions;
using CivitaiSharp.Tools.Downloads;
using CivitaiSharp.Tools.Extensions;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddCivitaiApi();
services.AddCivitaiDownloads(options =>
{
    options.Images.BaseDirectory = @"C:\Downloads\Images";
    options.Images.PathPattern = "{Username}/{Id}.{Extension}";

    options.Models.BaseDirectory = @"C:\Models";
    options.Models.PathPattern = "{ModelType}/{ModelName}/{FileName}";
    options.Models.VerifyHash = true;
});

await using var provider = services.BuildServiceProvider();
var apiClient = provider.GetRequiredService<IApiClient>();
var downloadService = provider.GetRequiredService<IDownloadService>();

// Download a model file with hash verification
var modelResult = await apiClient.Models.GetByIdAsync(4201);
if (modelResult.IsSuccess)
{
    var version = modelResult.Value.ModelVersions?.FirstOrDefault();
    var file = version?.Files?.FirstOrDefault(f => f.Primary == true);

    if (file is not null && version is not null)
    {
        var downloadResult = await downloadService.DownloadAsync(file, version);
        if (downloadResult.IsSuccess)
        {
            Console.WriteLine($"Downloaded: {downloadResult.Value.FilePath}");
            Console.WriteLine($"Verified: {downloadResult.Value.IsVerified}");
        }
    }
}

Tools - HTML Parsing

using CivitaiSharp.Tools.Parsing;

// Convert HTML description to Markdown
var markdown = HtmlParser.ToMarkdown(model.Description);

// Convert to plain text
var plainText = HtmlParser.ToPlainText(model.Description);

// Or use extension methods on Model/ModelVersion
var markdown = model.GetDescriptionAsMarkdown();
var plainText = modelVersion.GetDescriptionAsPlainText();

Error Handling

var result = await client.Models.ExecuteAsync();

// Pattern matching
var message = result switch
{
    { IsSuccess: true, Value: var page } => $"Found {page.Items.Count} models",
    { IsSuccess: false, ErrorInfo: var error } => error.Code switch
    {
        ErrorCode.RateLimited => "Too many requests, please slow down",
        ErrorCode.Unauthorized => "Invalid or missing API key",
        ErrorCode.NotFound => "Resource not found",
        _ => $"Error: {error.Code} - {error.Message}"
    }
};

// Traditional approach
if (result.IsSuccess)
{
    foreach (var model in result.Value.Items)
        Console.WriteLine(model.Name);
}
else
{
    Console.WriteLine($"Failed: {result.ErrorInfo.Message}");
}

6. Features

• Modern .NET 10 - Built with nullable reference types, records, and primary constructors
• Fluent Query Builders - Type-safe, immutable builders for constructing API requests
• Result Pattern - Explicit success/failure handling with discriminated union
• Built-in Resilience - Retry policies, circuit breakers, rate limiting, and timeouts
• Dependency Injection - First-class support for IHttpClientFactory and Microsoft DI
• Streaming Downloads - Memory-efficient response handling with ResponseHeadersRead
• Explicit JSON Contract - All model properties use [JsonPropertyName] for type safety

7. Documentation

• API Reference
• Getting Started Guide

8. Known API Quirks

CivitaiSharp interacts with the Civitai.com API, which has several known quirks. Some are mitigated automatically; others are documented and under investigation.

Creator Endpoint Reliability Issues

The /api/v1/creators endpoint is known to experience intermittent reliability issues:

• HTTP 500 errors: The endpoint frequently returns server errors, especially under load
• Slow response times: Requests may take significantly longer than other endpoints (10-30+ seconds)
• Timeout failures: Long response times can exceed client timeout thresholds

Recommendations:

1. Implement generous timeouts: Set timeouts of 60-120 seconds for Creator endpoint requests
2. Use retry logic: The built-in resilience handler will retry on 500 errors, but success is not guaranteed
3. Handle failures gracefully: Your application should degrade gracefully when Creator data is unavailable
4. Cache results aggressively: When requests succeed, cache the results to reduce API load

// Example: Handling Creator endpoint unreliability
var result = await client.Creators.ExecuteAsync(resultsLimit: 10);

if (!result.IsSuccess)
{
    // Log the error but continue with degraded functionality
    logger.LogWarning("Creator data unavailable: {Error}", result.ErrorInfo.Message);
    return GetCachedCreators(); // Fallback to cached data
}

Additional quirks are being tracked and will be addressed in future releases.

9. Versioning

CivitaiSharp follows MAJOR.MINOR.PATCH semantic versioning:

Pre-release versions use the format: MAJOR.MINOR.PATCH-alpha.N

Note: While in Alpha (0.x.x), APIs may change between minor versions. Stability is guaranteed from v1.0.0 onwards.

10. License

This repository is released under the MIT License.

11. Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines.

Legal Notice

CivitaiSharp is an independent open-source project and is not affiliated with, sponsored by, endorsed by, or officially associated with Civitai.com or Civitai, Inc. The Civitai name and any related trademarks are the property of their respective owners. Use of these names is for identification purposes only and does not imply any endorsement or partnership.

GitHub | Documentation | Civitai