horde_sdk.generation_parameters.image.object_models¶

class ControlnetFeatureFlags(GenerationParameterBaseModel):
    """Represents required or supported ControlNet render features."""

    model_config = get_default_frozen_model_config_dict()

    controlnets: list[KNOWN_IMAGE_CONTROLNETS | str] = Field(
        examples=[
            [KNOWN_IMAGE_CONTROLNETS.canny],
            [KNOWN_IMAGE_CONTROLNETS.canny, KNOWN_IMAGE_CONTROLNETS.depth],
        ],
    )
    """The controlnets supported by the worker."""

    image_is_control: bool = Field(default=False)
    """Whether there is support for passing a pre-parsed control image."""

    return_control_map: bool = Field(default=False)
    """Whether there is support returning the control map."""

class ImageGenerationFeatureFlags(GenerationFeatureFlags):
    """Represents portable image render features that are required or supported.

    A generation uses this model to describe requirements. A worker advertises the same fields as
    supported values inside `ImageWorkerFeatureFlags`. Compatibility is directional: every requested
    value must appear in the worker's advertised set, while a false, empty, or absent request field
    adds no requirement.
    """

    baselines: list[KNOWN_IMAGE_GENERATION_BASELINE | str] = Field(
        examples=[
            [KNOWN_IMAGE_GENERATION_BASELINE.infer],
            [KNOWN_IMAGE_GENERATION_BASELINE.infer, KNOWN_IMAGE_GENERATION_BASELINE.stable_diffusion_1],
        ],
    )
    """The baselines required by a generation or supported by a worker.

    If `infer`, the worker will attempt to infer the model type from the model name.
    """

    clip_skip: bool = Field(default=False)
    """Whether clip skipping is required or supported."""

    hires_fix: bool = Field(default=False)
    """Whether hires fix is required or supported."""

    tiling: bool = Field(default=False)
    """Whether seamless tiling is required or supported."""

    schedulers: list[KNOWN_IMAGE_SCHEDULERS | str] = Field(
        examples=[
            [KNOWN_IMAGE_SCHEDULERS.normal],
            [KNOWN_IMAGE_SCHEDULERS.normal, KNOWN_IMAGE_SCHEDULERS.simple],
        ],
    )
    """The schedulers required or supported."""

    samplers: list[KNOWN_IMAGE_SAMPLERS | str] = Field(
        examples=[
            [KNOWN_IMAGE_SAMPLERS.k_euler],
            [KNOWN_IMAGE_SAMPLERS.k_lms, KNOWN_IMAGE_SAMPLERS.k_euler],
        ],
    )
    """The samplers required or supported."""

    sampler_solver_knobs: list[SAMPLER_SOLVER_KNOB | str] | None = Field(default=None)
    """The per-request sampler solver knobs required or supported."""

    flow_shift: bool = Field(default=False)
    """Whether a model-specific flow shift is required or supported."""

    transparent: bool = Field(default=False)
    """Whether transparent image generation is required or supported."""

    controlnets_feature_flags: ControlnetFeatureFlags | None = Field(
        default=None,
        examples=[
            ControlnetFeatureFlags(
                controlnets=[KNOWN_IMAGE_CONTROLNETS.canny],
                image_is_control=False,
                return_control_map=False,
            ),
            ControlnetFeatureFlags(
                controlnets=[KNOWN_IMAGE_CONTROLNETS.canny, KNOWN_IMAGE_CONTROLNETS.depth],
                image_is_control=True,
                return_control_map=True,
            ),
        ],
    )
    """The ControlNet features required or supported."""

    post_processing: list[KNOWN_ALCHEMY_TYPES | str] | None = Field(
        default=None,
        examples=[
            [KNOWN_ALCHEMY_TYPES.RealESRGAN_x4plus],
            [KNOWN_ALCHEMY_TYPES.RealESRGAN_x4plus, KNOWN_ALCHEMY_TYPES.GFPGAN],
        ],
    )
    """The exact post-processing operations required or supported."""

    source_processing: list[KNOWN_IMAGE_SOURCE_PROCESSING | str] = Field(
        examples=[
            [KNOWN_IMAGE_SOURCE_PROCESSING.txt2img],
            [KNOWN_IMAGE_SOURCE_PROCESSING.txt2img, KNOWN_IMAGE_SOURCE_PROCESSING.img2img],
            [
                KNOWN_IMAGE_SOURCE_PROCESSING.txt2img,
                KNOWN_IMAGE_SOURCE_PROCESSING.img2img,
                KNOWN_IMAGE_SOURCE_PROCESSING.inpainting,
            ],
        ],
    )
    """The source-processing methods required or supported."""

    workflows: list[KNOWN_IMAGE_WORKFLOWS | str] | None = Field(
        default=None,
        examples=[
            [KNOWN_IMAGE_WORKFLOWS.qr_code],
        ],
    )
    """The workflows required or supported."""

    tis: list[KNOWN_AUX_MODEL_SOURCE | str] | None = Field(
        default=None,
        examples=[
            [KNOWN_AUX_MODEL_SOURCE.HORDELING],
            [KNOWN_AUX_MODEL_SOURCE.LOCAL],
        ],
    )
    """If textual inversions are supported, the sources of the textual inversions supported."""

    loras: list[KNOWN_AUX_MODEL_SOURCE | str] | None = Field(
        default=None,
        examples=[
            [KNOWN_AUX_MODEL_SOURCE.CIVITAI],
            [KNOWN_AUX_MODEL_SOURCE.LOCAL],
        ],
    )

    """If loras are supported, the sources of the loras supported."""

    @field_validator("baselines")
    @classmethod
    def ensure_baseline_non_empty(
        cls,
        v: list[KNOWN_IMAGE_GENERATION_BASELINE | str],
    ) -> list[KNOWN_IMAGE_GENERATION_BASELINE | str]:
        """Ensure that the baselines are not empty."""
        if not v:
            raise ValueError("Baselines cannot be empty.")
        return v

class BasicImageGenerationParametersTemplate(GenerationWithModelParameters):
    """Represents the common parameters for an image generation."""

    prompt: str | None = None
    """The prompt to use for the generation."""
    negative_prompt: str | None = None
    """The negative prompt to use for the generation, if any.

    Dispatch converters are responsible for splitting any combined prompt encoding
    (such as AI-Horde's ``###`` separator) before constructing these parameters.
    """
    seed: str | None = None
    """The seed to use for the generation."""

    height: int | None = Field(
        default=None,
        multiple_of=64,
        ge=64,
        examples=[512, 768],
    )
    """The height to use for the generation."""
    width: int | None = Field(
        default=None,
        multiple_of=64,
        ge=64,
        examples=[512, 768],
    )
    """The width to use for the generation."""

    steps: int | None = Field(
        default=None,
        ge=1,
        examples=[4, 20, 50],
    )
    """The number of steps to use for the generation."""

    cfg_scale: float | None = Field(
        default=None,
        ge=0,
        examples=[0.0, 1.0, 7.0],
    )
    """The scale to use for the generation."""

    sampler_name: KNOWN_IMAGE_SAMPLERS | str | None = Field(
        default=None,
        examples=[KNOWN_IMAGE_SAMPLERS.k_lms],
    )
    """The sampler to use for the generation."""

    scheduler: KNOWN_IMAGE_SCHEDULERS | str | None = Field(
        default=None,
        examples=[KNOWN_IMAGE_SCHEDULERS.normal],
    )
    """The scheduler to use for the generation."""

    sampler_eta: float | None = Field(
        default=None,
        ge=0,
        examples=[0.0, 1.0],
    )
    """The stochastic strength of the solver. Unset leaves the solver's own default in place.

    Which solvers accept this, and over what range, is stated in
    [`SAMPLER_CONSTRAINTS`][horde_sdk.generation_parameters.image.constraints.SAMPLER_CONSTRAINTS].
    """

    sampler_s_noise: float | None = Field(
        default=None,
        ge=0,
        examples=[1.0],
    )
    """The multiplier on the noise the solver adds per step. Unset leaves the solver's own default."""

    sampler_s_churn: float | None = Field(
        default=None,
        ge=0,
        examples=[0.0],
    )
    """The extra noise injected across the run, spread over the steps inside the churn window."""

    sampler_s_tmin: float | None = Field(
        default=None,
        ge=0,
        examples=[0.0],
    )
    """The lower sigma bound of the churn window. Only meaningful alongside `sampler_s_churn`."""

    sampler_s_tmax: float | None = Field(
        default=None,
        ge=0,
        examples=[999.0],
    )
    """The upper sigma bound of the churn window. Only meaningful alongside `sampler_s_churn`."""

    sampler_solver_type: KNOWN_SAMPLER_SOLVER_TYPES | str | None = Field(
        default=None,
        examples=[KNOWN_SAMPLER_SOLVER_TYPES.midpoint],
    )
    """Which correction the solver applies. The accepted vocabulary differs per sampler."""

    sampler_order: int | None = Field(
        default=None,
        ge=1,
        examples=[3, 4],
    )
    """The order of the solver. The accepted range is per-sampler and narrower than this bound."""

    flow_shift: float | None = Field(
        default=None,
        ge=0,
        examples=[3.0],
    )
    """The timestep shift applied to a flow-matching model. Unset leaves the model's own default."""

    clip_skip: int | None = Field(
        default=None,
        examples=[-3, -2, -1, 1, 2, 3],
    )
    """The offset of layer numbers to skip. Be sure to check `clip_skip_representation` for the representation."""

    clip_skip_representation: CLIP_SKIP_REPRESENTATION | None = Field(
        default=None,
    )
    """The representation of the clip skip. See `CLIP_SKIP_REPRESENTATION` for more information.

    Typically front-ends use positive values, while comfyui used the same value but negative.
    """

    denoising_strength: float | None = Field(
        default=None,
        ge=0,
        le=1,
        examples=[0.0, 0.5, 1.0],
    )
    """The denoising strength to use for the generation."""

    tiling: bool | None = None
    """If true, the generation will be generated with seamless tiling."""

    transparent: bool | None = None
    """If true, the generation will be generated with a transparent background (layer diffusion)."""

class BasicImageGenerationParameters(BasicImageGenerationParametersTemplate):
    """Represents the common bare minimum parameters for an image generation."""

    model_config = ConfigDict(
        frozen=True,
        from_attributes=True,
    )

    model: str
    """The model to use for the generation."""

    prompt: str
    """The prompt to use for the generation."""

    height: int | None = Field(
        default=DEFAULT_BASELINE_RESOLUTION,
        multiple_of=64,
        ge=64,
        examples=[512, 768],
    )
    """The height to use for the generation."""
    width: int | None = Field(
        default=DEFAULT_BASELINE_RESOLUTION,
        multiple_of=64,
        ge=64,
        examples=[512, 768],
    )
    """The width to use for the generation."""

    clip_skip_representation: CLIP_SKIP_REPRESENTATION | None = Field(
        default=CLIP_SKIP_REPRESENTATION.NEGATIVE_OFFSET,
    )
    """The representation of the clip skip. See `CLIP_SKIP_REPRESENTATION` for more information.

    Typically front-ends use positive values, while comfyui used the same value but negative.
    """

class Image2ImageGenerationParameters(GenerationParameterBaseModel):
    """Represents the parameters for an image-to-image generation."""

    source_image: bytes | str | None
    """The source image to use for the generation."""
    source_mask: bytes | str | None
    """The source mask to use for the generation."""

class RemixImageEntry(GenerationParameterBaseModel):
    """Represents a special image entry for a generation."""

    image: bytes | str
    """The image data."""

    strength: float = 1.0
    """The weight to apply this image to the remix generation."""

class RemixGenerationParameters(GenerationParameterBaseModel):
    """Represents the parameters for a stable cascade remix generation."""

    source_image: bytes | str
    """The source image to use for the generation."""

    remix_images: list[RemixImageEntry]
    """The images to remix the source image with."""

class ControlnetGenerationParameters(GenerationParameterBaseModel):
    """Represents the parameters for a controlnet generation."""

    controlnet_type: KNOWN_IMAGE_CONTROLNETS | str
    """The type of controlnet to use for the generation."""

    source_image: bytes | str | None
    """The source image to use for the generation, if img2img."""
    control_map: bytes | str | None
    """The control map to use for the generation, if img2img."""

    return_control_map: bool = False
    """If true, return the control map created by the controlnet pre-processor."""

    control_strength: float | None = None
    """The strength of the controlnet guidance. Unset leaves the backend's own default of 1.0."""

class HiresFixGenerationParameters(GenerationParameterBaseModel):
    """Represents the parameters for a high-resolution fix generation."""

    first_pass: BasicImageGenerationParameters
    second_pass: BasicImageGenerationParameters

class AuxModelEntry(GenerationParameterBaseModel):
    """Represents a single entry of an aux model, (LoRas, TIs, etc)."""

    name: str | None
    """The name of the aux model. If this is a hosted aux model, the name to search for. See `remote_version_id` if
    targeting a specific version of a hosted aux model."""
    release_version: str | None = None
    """The version of the aux model. This is v1, v2, etc. If this is a hosted aux model, you should instead use
    `remote_version_id` and reference the platform-specific file identifier."""
    remote_version_id: str | None
    """If this aux model is sourced from a website/API, the version ID specific to that website/API
    to identify the specific version of the aux model. This is *not* v1, v2, but a numeric ID that the
    service assigns and is typically in the URL of the download link."""

    source: KNOWN_AUX_MODEL_SOURCE | str
    """The source of the aux model. This can be a known source or a custom source."""

    remote_url: str | None = None
    """The remote URL to download the aux model from."""
    local_filename: Path | None = None
    """The local filename to load the aux model from."""
    file_hash: str | None = None
    """The hash of the aux model file."""

    model_strength: float = 1
    """The strength of the aux model on the generation model. 1 is the default strength."""

    @model_validator(mode="after")
    def verify_identifier_set(self: AuxModelEntry) -> AuxModelEntry:
        """Ensure that at least one of name, version, or remote_version_id is provided."""
        if self.name is None and self.release_version is None and self.remote_version_id is None:
            raise ValueError("At least one of name, version, or remote_version_id must be provided.")

        return self

class LoRaEntry(AuxModelEntry):
    """Represents a single entry of a LoRa."""

    clip_strength: float = 1
    """The strength of the LoRa on the clip model. 1 is the default strength."""

    lora_triggers: list[str] | None = None
    """The triggers to use for the LoRa. Specify the behavior with `lora_inject_trigger_choice`."""

    lora_inject_trigger_choice: LORA_TRIGGER_INJECT_CHOICE = LORA_TRIGGER_INJECT_CHOICE.NO_INJECT
    """If true and if supported by the backend, inject a trigger term into the prompt."""

class TIEntry(AuxModelEntry):
    """Represents a single entry of a Textual Inversion."""

    ti_inject_trigger_choice: TI_TRIGGER_INJECT_CHOICE = TI_TRIGGER_INJECT_CHOICE.NO_INJECT
    """If true and if supported by the backend, inject a trigger term into the prompt."""

class ExtraTextEntry(GenerationParameterBaseModel):
    """Represents a single extra text input consumed by a custom workflow."""

    text: str
    """The text content."""

    reference: str | None = None
    """A reference identifying how the workflow should use this text."""

class CustomWorkflowGenerationParameters(GenerationParameterBaseModel):
    """Represents the parameters for a custom workflow generation."""

    custom_workflow_name: KNOWN_IMAGE_WORKFLOWS | str
    """The name of the custom workflow to use for the generation."""
    custom_workflow_version: str | None = None
    """The version of the custom workflow to use for the generation. \
        If None, the latest version will be used. Defaults to None."""

    custom_parameters: dict[ID_TYPES, str] | None = None
    """The custom parameters to use for the generation. Defaults to None."""

    extra_texts: list[ExtraTextEntry] | None = None
    """Extra text inputs consumed by the workflow (for example, the text encoded by a QR code workflow)."""

class ImageGenerationComponentContainer(GenerationParameterBaseModel):
    """Container for optional image generation components.

    This container holds auxiliary components for image generation such as LoRa entries,
    Textual Inversion entries, ControlNet parameters, and more. It uses a simple list
    that naturally supports multiple instances of the same component type.
    """

    model_config = ConfigDict(
        use_attribute_docstrings=True,
        from_attributes=True,
    )

    components: list[
        Image2ImageGenerationParameters
        | RemixGenerationParameters
        | ControlnetGenerationParameters
        | HiresFixGenerationParameters
        | LoRaEntry
        | TIEntry
        | CustomWorkflowGenerationParameters
    ] = Field(default_factory=list)
    """The list of generation components."""

    def add(
        self,
        component: (
            Image2ImageGenerationParameters
            | RemixGenerationParameters
            | ControlnetGenerationParameters
            | HiresFixGenerationParameters
            | LoRaEntry
            | TIEntry
            | CustomWorkflowGenerationParameters
        ),
    ) -> None:
        """Add a component to the container.

        Args:
            component: The component to add.
        """
        self.components.append(component)

    def add_all(
        self,
        components: list[
            Image2ImageGenerationParameters
            | RemixGenerationParameters
            | ControlnetGenerationParameters
            | HiresFixGenerationParameters
            | LoRaEntry
            | TIEntry
            | CustomWorkflowGenerationParameters
        ],
    ) -> None:
        """Add multiple components to the container.

        Args:
            components: The list of components to add.
        """
        self.components.extend(components)

    @property
    def image2image_params(self) -> Image2ImageGenerationParameters | None:
        """Get the image-to-image parameters if they exist."""
        for component in self.components:
            if isinstance(component, Image2ImageGenerationParameters):
                return component
        return None

    @property
    def remix_params(self) -> RemixGenerationParameters | None:
        """Get the remix parameters if they exist."""
        for component in self.components:
            if isinstance(component, RemixGenerationParameters):
                return component
        return None

    @property
    def controlnet_params(self) -> ControlnetGenerationParameters | None:
        """Get the controlnet parameters if they exist."""
        for component in self.components:
            if isinstance(component, ControlnetGenerationParameters):
                return component
        return None

    @property
    def hires_fix_params(self) -> HiresFixGenerationParameters | None:
        """Get the hires fix parameters if they exist."""
        for component in self.components:
            if isinstance(component, HiresFixGenerationParameters):
                return component
        return None

    @property
    def lora_entries(self) -> list[LoRaEntry]:
        """Get all LoRa entries."""
        return [c for c in self.components if isinstance(c, LoRaEntry)]

    @property
    def ti_entries(self) -> list[TIEntry]:
        """Get all Textual Inversion entries."""
        return [c for c in self.components if isinstance(c, TIEntry)]

    @property
    def custom_workflow_entries(self) -> list[CustomWorkflowGenerationParameters]:
        """Get all custom workflow entries."""
        return [c for c in self.components if isinstance(c, CustomWorkflowGenerationParameters)]

    @property
    def lora_params(self) -> list[LoRaEntry]:
        """Get all LoRa entries.

        Deprecated: Use lora_entries instead. This property returns a plain list instead of LoRaEntries wrapper.
        """
        return self.lora_entries

    @property
    def ti_params(self) -> list[TIEntry]:
        """Get all Textual Inversion entries.

        Deprecated: Use ti_entries instead. This property returns a plain list instead of TIEntries wrapper.
        """
        return self.ti_entries

    @property
    def custom_workflows_params(self) -> list[CustomWorkflowGenerationParameters]:
        """Get all custom workflow entries.

        Deprecated: Use custom_workflow_entries instead. This property returns a plain list instead of
        CustomWorkflows wrapper.
        """
        return self.custom_workflow_entries