Class ModelBuilder

Namespace

CivitaiSharp.Core.Request

Assembly

CivitaiSharp.Core.dll

Immutable, thread-safe request builder for models. 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 ModelBuilder : RequestBuilder<ModelBuilder, Model>, IEquatable<RequestBuilder<ModelBuilder, Model>>, IEquatable<ModelBuilder>

Inheritance

object

RequestBuilder<ModelBuilder, Model>

ModelBuilder

Implements

IEquatable<RequestBuilder<ModelBuilder, Model>>

IEquatable<ModelBuilder>

Inherited Members

RequestBuilder<ModelBuilder, Model>.ExecuteAsync(int?, string, CancellationToken)

RequestBuilder<ModelBuilder, Model>.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 (100).

public const int MaximumResultsPerPage = 100

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 models 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 models endpoint has a maximum limit of 100.

MinResultsLimit

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

protected override int MinResultsLimit { get; }

Property Value

int

Remarks

The models endpoint requires a minimum limit of 1.

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

GetByIdAsync(long, CancellationToken)

Gets a model by its unique identifier.

public Task<Result<Model>> GetByIdAsync(long id, CancellationToken cancellationToken = default)

Parameters

id long

The model identifier. Must be a positive value.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<Model>>

A task that represents the asynchronous operation. The result contains either the model or an error.

Exceptions

ArgumentOutOfRangeException

Thrown if id is less than 1.

GetByVersionHashAsync(string, CancellationToken)

Gets a model version by one of its file hashes (SHA256, AutoV2, CRC32, etc.).

public Task<Result<ModelVersion>> GetByVersionHashAsync(string hash, CancellationToken cancellationToken = default)

Parameters

hash string

The file hash to search for. Must not be null or whitespace.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<ModelVersion>>

A task that represents the asynchronous operation. The result contains either the model version or an error.

Exceptions

ArgumentException

Thrown if hash is null or whitespace.

GetByVersionIdAsync(long, CancellationToken)

Gets a model version by its unique version identifier.

public Task<Result<ModelVersion>> GetByVersionIdAsync(long versionId, CancellationToken cancellationToken = default)

Parameters

versionId long

The model version identifier. Must be a positive value.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<ModelVersion>>

A task that represents the asynchronous operation. The result contains either the model version or an error.

Exceptions

ArgumentOutOfRangeException

Thrown if versionId is less than 1.

OrderBy(ModelSort)

Order results by a model sort option.

public ModelBuilder OrderBy(ModelSort sort)

Parameters

sort ModelSort

The sort option to apply.

Returns

ModelBuilder

A new builder instance with the sort applied.

Remarks

Sort values containing spaces (e.g., "Highest Rated", "Most Downloaded") are automatically URL-encoded. The API accepts both URL-encoded and raw space characters, but encoding is recommended for reliability.

Exceptions

ArgumentOutOfRangeException

Thrown if sort is not a defined enum value.

WhereAllowDerivatives(bool)

Filter by allowDerivatives permission.

public ModelBuilder WhereAllowDerivatives(bool allowed)

Parameters

allowed bool

True to filter for models that allow derivatives, false otherwise.

Returns

ModelBuilder

A new builder instance with the filter applied.

Remarks

Note: Testing shows this filter may return 0 results regardless of the value. This could be an API-side behavior, a data condition requirement, or require additional context. Use with caution and verify results match expectations.

WhereAllowDifferentLicenses(bool)

Filter by allowDifferentLicenses permission.

public ModelBuilder WhereAllowDifferentLicenses(bool allowed)

Parameters

allowed bool

True to filter for models that allow different licenses on derivatives, false otherwise.

Returns

ModelBuilder

A new builder instance with the filter applied.

WhereAllowNoCredit(bool)

Filter by allowNoCredit permission.

public ModelBuilder WhereAllowNoCredit(bool allowed)

Parameters

allowed bool

True to filter for models that allow use without credit, false otherwise.

Returns

ModelBuilder

A new builder instance with the filter applied.

Remarks

Note: Testing shows this filter may return 0 results regardless of the value. This could be an API-side behavior, a data condition requirement, or require additional context. Use with caution and verify results match expectations.

WhereBaseModel(string)

Filter models by base model type (e.g., "SD 1.5", "SDXL 1.0", "Flux.1 D").

public ModelBuilder WhereBaseModel(string baseModel)

Parameters

baseModel string

The base model type to filter by.

Returns

ModelBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentException

Thrown if baseModel is null or whitespace.

WhereBaseModels(params string[])

Filter models by multiple base model types (e.g., "SD 1.5", "SDXL 1.0", "Flux.1 D").

public ModelBuilder WhereBaseModels(params string[] baseModels)

Parameters

baseModels string[]

The base model types to filter by. Must contain at least one value.

Returns

ModelBuilder

A new builder instance with the filter applied.

Remarks

Multiple base models are sent as repeated query parameters (e.g., baseModels=SD%201.5&baseModels=SDXL%201.0). Values containing spaces are automatically URL-encoded.

Important: Unlike the ids parameter, comma-separated values for baseModels will result in a 400 Bad Request error. Only the repeated parameter format is supported for base models.

Exceptions

ArgumentException

Thrown if baseModels is null, empty, or contains null/whitespace values.

WhereCommercialUse(params CommercialUsePermission[])

Filter by commercial use permissions. The API accepts multiple permission levels and returns models matching any of them (OR logic).

public ModelBuilder WhereCommercialUse(params CommercialUsePermission[] permissions)

Parameters

permissions CommercialUsePermission[]

The commercial use permission levels to filter by. Must contain at least one value.

Returns

ModelBuilder

A new builder instance with the filter applied.

Remarks

Testing shows that the API requires at least two permission values to return results. Single values (e.g., only None) typically return 0 results. This behavior may be API-specific or reflect the underlying data model.

Multiple values are sent as repeated query parameters (e.g., allowCommercialUse=Image&allowCommercialUse=Sell). The API interprets this as an OR filter, returning models that match any of the specified permissions.

Exceptions

ArgumentException

Thrown if permissions is null or empty.

ArgumentOutOfRangeException

Thrown if any permission is not a defined enum value.

WhereFavorites()

Restrict results to favorites for the authenticated user.

public ModelBuilder WhereFavorites()

Returns

ModelBuilder

A new builder instance with the filter applied.

Remarks

Requires authentication. This filter requires a valid API key to be configured via Key. Without authentication, this filter will return 0 results.

WhereHidden()

Restrict results to hidden models.

public ModelBuilder WhereHidden()

Returns

ModelBuilder

A new builder instance with the filter applied.

Remarks

Requires authentication. This filter requires a valid API key to be configured via Key. Without authentication, this filter will return 0 results. Hidden models are models that the authenticated user has explicitly hidden from their feed.

WhereIds(params long[])

Filter models by specific model IDs. This filter is ignored if a query is also provided.

public ModelBuilder WhereIds(params long[] ids)

Parameters

ids long[]

The model IDs to filter by. Must contain at least one value, and all values must be positive.

Returns

ModelBuilder

A new builder instance with the filter applied.

Remarks

Multiple IDs are sent as repeated query parameters (e.g., ids=122359&ids=58390) or can be comma-separated (e.g., ids=122359,58390). Both formats work correctly for the ids parameter.

Exceptions

ArgumentException

Thrown if ids is null or empty.

ArgumentOutOfRangeException

Thrown if any id is less than 1.

WhereName(string)

Filter models by name (search query parameter).

public ModelBuilder WhereName(string name)

Parameters

name string

The model name to search for.

Returns

ModelBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentException

Thrown if name is null or whitespace.

WhereNsfw(bool)

Filter NSFW models.

public ModelBuilder WhereNsfw(bool nsfw)

Parameters

nsfw bool

True to include only NSFW models, false to exclude them.

Returns

ModelBuilder

A new builder instance with the filter applied.

WherePeriod(TimePeriod)

Restrict results to a specific time period.

public ModelBuilder WherePeriod(TimePeriod period)

Parameters

period TimePeriod

The time period to filter by.

Returns

ModelBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentOutOfRangeException

Thrown if period is not a defined enum value.

WherePrimaryFileOnly()

Only include primary file models.

public ModelBuilder WherePrimaryFileOnly()

Returns

ModelBuilder

A new builder instance with the filter applied.

WhereSupportsGeneration(bool)

Filter models that support generation.

public ModelBuilder WhereSupportsGeneration(bool supported)

Parameters

supported bool

True to include only models that support generation, false otherwise.

Returns

ModelBuilder

A new builder instance with the filter applied.

WhereTag(string)

Filter models by a single tag.

public ModelBuilder WhereTag(string tag)

Parameters

tag string

The tag to filter by.

Returns

ModelBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentException

Thrown if tag is null or whitespace.

WhereType(ModelType)

Filter models by model type.

public ModelBuilder WhereType(ModelType type)

Parameters

type ModelType

The model type to filter by.

Returns

ModelBuilder

A new builder instance with the filter applied.

Exceptions

ArgumentOutOfRangeException

Thrown if type is not a defined enum value.

WhereUsername(string)

Filter models by creator username.

public ModelBuilder WhereUsername(string username)

Parameters

username string

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

Returns

ModelBuilder

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 ModelBuilder 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

ModelBuilder

A new builder instance with the updated state.

WithPageIndex(int)

Set the page index for page-based pagination.

public ModelBuilder WithPageIndex(int pageIndex)

Parameters

pageIndex int

The 1-based page index. Must be at least 1.

Returns

ModelBuilder

A new builder instance with the page index applied.

Exceptions

ArgumentOutOfRangeException

Thrown if pageIndex is less than 1.