Class ImageBuilder

Namespace

CivitaiSharp.Core.Request

Assembly

CivitaiSharp.Core.dll

Immutable, thread-safe request builder for images. Use the fluent methods to compose filters, then call ExecuteAsync(int?, string?, CancellationToken) to execute the request. Each fluent method returns a new builder instance, allowing safe reuse and caching of base configurations.

public sealed record ImageBuilder : RequestBuilder<ImageBuilder, Image>, IEquatable<RequestBuilder<ImageBuilder, Image>>, IEquatable<ImageBuilder>

Inheritance

object

RequestBuilder<ImageBuilder, Image>

ImageBuilder

Implements

IEquatable<RequestBuilder<ImageBuilder, Image>>

IEquatable<ImageBuilder>

Inherited Members

RequestBuilder<ImageBuilder, Image>.ExecuteAsync(int?, string, CancellationToken)

RequestBuilder<ImageBuilder, Image>.FirstOrDefaultAsync(CancellationToken)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Fields

MaximumResultsPerPage

The maximum allowed value for the resultsLimit parameter in ExecuteAsync (200).

public const int MaximumResultsPerPage = 200

Field Value

int

MinimumResultsPerPage

The minimum allowed value for the resultsLimit parameter in ExecuteAsync (1).

public const int MinimumResultsPerPage = 1

Field Value

int

Properties

DefaultResultsLimit

Gets the default results limit when none is specified for this endpoint.

protected override int DefaultResultsLimit { get; }

Property Value

int

Remarks

The images endpoint returns 100 results by default.

Endpoint

Gets the API endpoint path segment for this resource type (e.g., "models", "images").

protected override string Endpoint { get; }

Property Value

string

MaxResultsLimit

Gets the maximum allowed value for results limit for this endpoint.

protected override int MaxResultsLimit { get; }

Property Value

int

Remarks

The images endpoint has a maximum limit of 200.

MinResultsLimit

Gets the minimum allowed value for results limit for this endpoint.

protected override int MinResultsLimit { get; }

Property Value

int

Remarks

The images endpoint requires a minimum limit of 1. Omit the limit to return all results (up to 200 per page).

SupportsSorting

Gets a value indicating whether this endpoint supports sorting. Override to return true in derived classes that support sorting.

protected override bool SupportsSorting { get; }

Property Value

bool

Methods

OrderBy(ImageSort)

Order images by the given sort option.

public ImageBuilder OrderBy(ImageSort sort)

Parameters

sort ImageSort

The sort option to apply.

Returns

ImageBuilder

A new builder instance with the sort applied.

Exceptions

ArgumentOutOfRangeException

Thrown if sort is not a defined enum value.

WhereModelId(long)

Filter images by model id.

public ImageBuilder WhereModelId(long id)

Parameters

id long

The model identifier. Must be a positive value.

Returns

ImageBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentOutOfRangeException

Thrown if id is less than 1.

WhereModelVersionId(long)

Filter images by model version id.

public ImageBuilder WhereModelVersionId(long id)

Parameters

id long

The model version identifier. Must be a positive value.

Returns

ImageBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentOutOfRangeException

Thrown if id is less than 1.

WhereNsfwLevel(ImageNsfwLevel)

Filter images by NSFW level.

public ImageBuilder WhereNsfwLevel(ImageNsfwLevel level)

Parameters

level ImageNsfwLevel

The NSFW level to filter by.

Returns

ImageBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentOutOfRangeException

Thrown if level is not a defined enum value.

WherePeriod(TimePeriod)

Restrict results to a specific time period.

public ImageBuilder WherePeriod(TimePeriod period)

Parameters

period TimePeriod

The time period to filter by.

Returns

ImageBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentOutOfRangeException

Thrown if period is not a defined enum value.

WherePostId(long)

Filter images by post id.

public ImageBuilder WherePostId(long id)

Parameters

id long

The post identifier. Must be a positive value.

Returns

ImageBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentOutOfRangeException

Thrown if id is less than 1.

WhereUsername(string)

Filter images by the creator's username.

public ImageBuilder WhereUsername(string username)

Parameters

username string

The username to filter by. Must contain only letters, numbers, and underscores.

Returns

ImageBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentException

Thrown if username is null, whitespace, or contains invalid characters.

With(ImmutableDictionary<string, object?>, string?, int?)

Creates a new builder instance with the specified state changes. Derived classes must implement this to return the correct derived type.

protected override ImageBuilder With(ImmutableDictionary<string, object?> filters, string? sort, int? resultsLimit)

Parameters

filters ImmutableDictionary<string, object>

The new filters dictionary with typed values.

sort string

The new sort value.

resultsLimit int?

The new results limit.

Returns

ImageBuilder

A new builder instance with the updated state.