Class ImageGenerationBuilder

Namespace

CivitaiSharp.Sdk.Request

Assembly

CivitaiSharp.Sdk.dll

Immutable, thread-safe builder for constructing and submitting image generation jobs. Supports both text-to-image and image-to-image generation modes. Each fluent method returns a new builder instance, allowing safe reuse and caching of base configurations.

public sealed record ImageGenerationBuilder : IEquatable<ImageGenerationBuilder>

Inheritance

object

ImageGenerationBuilder

Implements

IEquatable<ImageGenerationBuilder>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Methods

ExecuteAsync(CancellationToken)

Executes the job submission to the Civitai Generator API.

public Task<Result<JobStatusCollection>> ExecuteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<JobStatusCollection>>

A task containing the job status collection with a token for polling.

Exceptions

InvalidOperationException

Thrown when required properties are missing.

ExecuteBatchAsync(IEnumerable<ImageGenerationBuilder>, CancellationToken)

Executes multiple job submissions as a batch to the Civitai Generator API.

public Task<Result<JobStatusCollection>> ExecuteBatchAsync(IEnumerable<ImageGenerationBuilder> additionalJobs, CancellationToken cancellationToken = default)

Parameters

additionalJobs IEnumerable<ImageGenerationBuilder>

Additional configured job builders to submit in the same batch.

cancellationToken CancellationToken

Token to cancel the asynchronous operation.

Returns

Task<Result<JobStatusCollection>>

A task containing the job status collection with a token for polling all jobs.

Exceptions

InvalidOperationException

Thrown when required properties are missing.

WithAdditionalNetwork(AirIdentifier, ImageJobNetworkParams)

Adds an additional network (LoRA, embedding, etc.) to the generation.

public ImageGenerationBuilder WithAdditionalNetwork(AirIdentifier network, ImageJobNetworkParams networkParams)

Parameters

network AirIdentifier

The AIR identifier for the network.

networkParams ImageJobNetworkParams

The network configuration.

Returns

ImageGenerationBuilder

A new builder instance with the added network.

WithAdditionalNetwork(AirIdentifier, NetworkBuilder)

Adds an additional network (LoRA, embedding, etc.) using a builder.

public ImageGenerationBuilder WithAdditionalNetwork(AirIdentifier network, NetworkBuilder networkBuilder)

Parameters

network AirIdentifier

The AIR identifier for the network.

networkBuilder NetworkBuilder

The configured network parameters builder.

Returns

ImageGenerationBuilder

A new builder instance with the added network.

WithAdditionalNetwork(AirIdentifier, Func<NetworkBuilder, NetworkBuilder>)

Adds an additional network (LoRA, embedding, etc.) using a configuration action.

public ImageGenerationBuilder WithAdditionalNetwork(AirIdentifier network, Func<NetworkBuilder, NetworkBuilder> configure)

Parameters

network AirIdentifier

The AIR identifier for the network.

configure Func<NetworkBuilder, NetworkBuilder>

Action to configure the network parameters builder.

Returns

ImageGenerationBuilder

A new builder instance with the added network.

WithAir(AirIdentifier)

Sets the base AIR identifier to use for generation.

public ImageGenerationBuilder WithAir(AirIdentifier air)

Parameters

air AirIdentifier

The AIR identifier. Required.

Returns

ImageGenerationBuilder

A new builder instance with the updated AIR identifier.

Examples

urn:air:sdxl:checkpoint:civitai:4201@130072

WithCallbackUrl(string)

Sets the webhook URL to call when the job completes.

public ImageGenerationBuilder WithCallbackUrl(string callbackUrl)

Parameters

callbackUrl string

The webhook URL.

Returns

ImageGenerationBuilder

A new builder instance with the updated callback URL.

WithClipSkip(int)

Sets the number of CLIP layers to skip.

public ImageGenerationBuilder WithClipSkip(int clipSkip)

Parameters

clipSkip int

The number of layers to skip. Range: 1-12.

Returns

ImageGenerationBuilder

A new builder instance with the updated CLIP skip.

Remarks

A value of 2 is commonly used for anime/Pony models. This can also be set via WithClipSkip(int).

WithConfigurationScale(decimal)

Sets the classifier-free guidance scale.

public ImageGenerationBuilder WithConfigurationScale(decimal configurationScale)

Parameters

configurationScale decimal

The configuration scale. Range: 1-30, default: 7.0.

Returns

ImageGenerationBuilder

A new builder instance with the updated configuration scale.

WithControlNet(ImageJobControlNet)

Adds a ControlNet configuration for guided generation.

public ImageGenerationBuilder WithControlNet(ImageJobControlNet controlNet)

Parameters

controlNet ImageJobControlNet

The ControlNet configuration.

Returns

ImageGenerationBuilder

A new builder instance with the added ControlNet.

WithControlNet(ControlNetBuilder)

Adds a ControlNet configuration using a builder.

public ImageGenerationBuilder WithControlNet(ControlNetBuilder controlNetBuilder)

Parameters

controlNetBuilder ControlNetBuilder

The configured ControlNet builder.

Returns

ImageGenerationBuilder

A new builder instance with the added ControlNet.

WithControlNet(Func<ControlNetBuilder, ControlNetBuilder>)

Adds a ControlNet configuration using a configuration action.

public ImageGenerationBuilder WithControlNet(Func<ControlNetBuilder, ControlNetBuilder> configure)

Parameters

configure Func<ControlNetBuilder, ControlNetBuilder>

Action to configure the ControlNet builder.

Returns

ImageGenerationBuilder

A new builder instance with the added ControlNet.

WithDenoisingStrength(decimal)

Sets the denoising strength for image-to-image generation.

public ImageGenerationBuilder WithDenoisingStrength(decimal denoisingStrength)

Parameters

denoisingStrength decimal

The strength value. Range: 0.0-1.0. Lower values preserve more of the source image.

Returns

ImageGenerationBuilder

A new builder instance with the updated denoising strength.

Remarks

Only applicable when a source image is provided via WithSourceImageUrl(string). Lower values (e.g., 0.3) preserve more of the source image, higher values (e.g., 0.8) allow more transformation.

WithDimensions(int, int)

Sets the image dimensions.

public ImageGenerationBuilder WithDimensions(int width, int height)

Parameters

width int

The width in pixels. Must be a multiple of 8. Range: 64-2048.

height int

The height in pixels. Must be a multiple of 8. Range: 64-2048.

Returns

ImageGenerationBuilder

A new builder instance with the updated dimensions.

WithNegativePrompt(string)

Sets the negative prompt describing what to avoid.

public ImageGenerationBuilder WithNegativePrompt(string negativePrompt)

Parameters

negativePrompt string

The negative prompt text.

Returns

ImageGenerationBuilder

A new builder instance with the updated negative prompt.

WithParams(ImageJobParamsBuilder)

Configures generation parameters using a custom builder.

public ImageGenerationBuilder WithParams(ImageJobParamsBuilder paramsBuilder)

Parameters

paramsBuilder ImageJobParamsBuilder

The configured parameters builder.

Returns

ImageGenerationBuilder

A new builder instance with the updated parameters.

WithParams(Func<ImageJobParamsBuilder, ImageJobParamsBuilder>)

Configures generation parameters using a configuration action.

public ImageGenerationBuilder WithParams(Func<ImageJobParamsBuilder, ImageJobParamsBuilder> configure)

Parameters

configure Func<ImageJobParamsBuilder, ImageJobParamsBuilder>

Action to configure the parameters builder.

Returns

ImageGenerationBuilder

A new builder instance with the updated parameters.

WithPositivePrompt(string)

Sets the positive prompt for image generation.

public ImageGenerationBuilder WithPositivePrompt(string positivePrompt)

Parameters

positivePrompt string

The prompt text describing what to generate. Required.

Returns

ImageGenerationBuilder

A new builder instance with the updated positive prompt.

WithPriority(Priority)

Sets the priority configuration for job scheduling.

public ImageGenerationBuilder WithPriority(Priority priority)

Parameters

priority Priority

The priority configuration.

Returns

ImageGenerationBuilder

A new builder instance with the updated priority.

WithProperty(string, bool)

Adds a custom boolean property for job tracking and querying.

public ImageGenerationBuilder WithProperty(string key, bool value)

Parameters

key string

The property key.

value bool

The boolean value.

Returns

ImageGenerationBuilder

A new builder instance with the added property.

WithProperty(string, DateTime)

Adds a custom DateTime property for job tracking and querying.

public ImageGenerationBuilder WithProperty(string key, DateTime value)

Parameters

key string

The property key.

value DateTime

The DateTime value.

Returns

ImageGenerationBuilder

A new builder instance with the added property.

WithProperty(string, decimal)

Adds a custom decimal property for job tracking and querying.

public ImageGenerationBuilder WithProperty(string key, decimal value)

Parameters

key string

The property key.

value decimal

The decimal value.

Returns

ImageGenerationBuilder

A new builder instance with the added property.

WithProperty(string, Guid)

Adds a custom GUID property for job tracking and querying.

public ImageGenerationBuilder WithProperty(string key, Guid value)

Parameters

key string

The property key.

value Guid

The GUID value.

Returns

ImageGenerationBuilder

A new builder instance with the added property.

WithProperty(string, int)

Adds a custom integer property for job tracking and querying.

public ImageGenerationBuilder WithProperty(string key, int value)

Parameters

key string

The property key.

value int

The integer value.

Returns

ImageGenerationBuilder

A new builder instance with the added property.

WithProperty(string, long)

Adds a custom long property for job tracking and querying.

public ImageGenerationBuilder WithProperty(string key, long value)

Parameters

key string

The property key.

value long

The long value.

Returns

ImageGenerationBuilder

A new builder instance with the added property.

WithProperty(string, string)

Adds a custom string property for job tracking and querying.

public ImageGenerationBuilder WithProperty(string key, string value)

Parameters

key string

The property key.

value string

The string value.

Returns

ImageGenerationBuilder

A new builder instance with the added property.

WithQuantity(int)

Sets the number of images to generate.

public ImageGenerationBuilder WithQuantity(int quantity)

Parameters

quantity int

The quantity. Range: 1-10, default: 1.

Returns

ImageGenerationBuilder

A new builder instance with the updated quantity.

WithRetries(int)

Sets the number of automatic retries on failure.

public ImageGenerationBuilder WithRetries(int retries)

Parameters

retries int

The number of retry attempts. Default: 0.

Returns

ImageGenerationBuilder

A new builder instance with the updated retry attempts.

WithScheduler(Scheduler)

Sets the sampling algorithm/scheduler to use for generation.

public ImageGenerationBuilder WithScheduler(Scheduler scheduler)

Parameters

scheduler Scheduler

The scheduler/sampler algorithm.

Returns

ImageGenerationBuilder

A new builder instance with the updated scheduler.

Remarks

Common schedulers include Euler, EulerAncestral, DpmPlusPlus2M, and DpmPlusPlus2MKarras. The choice of scheduler affects both generation quality and speed.

WithSeed(long)

Sets the random seed for reproducible generation.

public ImageGenerationBuilder WithSeed(long seed)

Parameters

seed long

The seed value.

Returns

ImageGenerationBuilder

A new builder instance with the updated seed.

WithSourceImageUrl(string)

Sets the source image URL for image-to-image generation.

public ImageGenerationBuilder WithSourceImageUrl(string sourceImageUrl)

Parameters

sourceImageUrl string

The URL of the source image. When provided, enables image-to-image mode.

Returns

ImageGenerationBuilder

A new builder instance with the updated source image URL.

Remarks

When a source image is provided, the generation becomes image-to-image mode. Use WithDenoisingStrength(decimal) to control how much the source image is transformed.

WithSteps(int)

Sets the number of sampling steps.

public ImageGenerationBuilder WithSteps(int steps)

Parameters

steps int

The step count. Range: 1-100, default: 20.

Returns

ImageGenerationBuilder

A new builder instance with the updated steps.

WithTimeout(string)

Sets the job timeout.

public ImageGenerationBuilder WithTimeout(string timeout)

Parameters

timeout string

The timeout duration. Format: "HH:mm:ss". Default: "00:10:00".

Returns

ImageGenerationBuilder

A new builder instance with the updated timeout.

WithTimeout(TimeSpan)

Sets the job timeout.

public ImageGenerationBuilder WithTimeout(TimeSpan timeout)

Parameters

timeout TimeSpan

The timeout duration. Default: 10 minutes.

Returns

ImageGenerationBuilder

A new builder instance with the updated timeout.