Invocation API#

Each invocation's invoke method is provided a single arg - the Invocation Context.

This object provides access to various methods, used to interact with the application. Loading and saving images, logging messages, etc.

This API may shift slightly until the release of v4.0.0 as we work through a few final updates to the Model Manager.

class MyInvocation(BaseInvocation):
  ...
  def invoke(self, context: InvocationContext) -> ImageOutput:
      image_pil = context.images.get_pil(image_name)
      # Do something to the image
      image_dto = context.images.save(image_pil)
      # Log a message
      context.logger.info(f"Did something cool, image saved!")
      ...

The full API is documented below.

Invocation Mixins#

Two important mixins are provided to facilitate working with metadata and gallery boards.

`WithMetadata`#

Inherit from this class (in addition to BaseInvocation) to add a metadata input to your node. When you do this, you can access the metadata dict from self.metadata in the invoke() function.

The dict will be populated via the node's input, and you can add any metadata you'd like to it. When you call context.images.save(), if the metadata dict has any data, it be automatically embedded in the image.

`WithBoard`#

Inherit from this class (in addition to BaseInvocation) to add a board input to your node. This renders as a drop-down to select a board. The user's selection will be accessible from self.board in the invoke() function.

When you call context.images.save(), if a board was selected, the image will added to that board as it is saved.

InvocationContext #

Provides access to various services and data for the current invocation.

Attributes:

Name	Type	Description
`images`	`ImagesInterface`	Methods to save, get and update images and their metadata.
`tensors`	`TensorsInterface`	Methods to save and get tensors, including image, noise, masks, and masked images.
`conditioning`	`ConditioningInterface`	Methods to save and get conditioning data.
`models`	`ModelsInterface`	Methods to check if a model exists, get a model, and get a model's info.
`logger`	`LoggerInterface`	The app logger.
`config`	`ConfigInterface`	The app config.
`util`	`UtilInterface`	Utility methods, including a method to check if an invocation was canceled and step callbacks.
`boards`	`BoardsInterface`	Methods to interact with boards.

ImagesInterface #

get_dto #

get_dto(image_name: str) -> ImageDTO

Gets an image as an ImageDTO object.

Parameters:

Name	Type	Description	Default
`image_name`	`str`	The name of the image to get.	required

Returns:

Type	Description
`ImageDTO`	The image as an ImageDTO object.

get_metadata #

get_metadata(image_name: str) -> Optional[MetadataField]

Gets an image's metadata, if it has any.

Parameters:

Name	Type	Description	Default
`image_name`	`str`	The name of the image to get the metadata for.	required

Returns:

Type	Description
`Optional[MetadataField]`	The image's metadata, if it has any.

get_path #

get_path(image_name: str, thumbnail: bool = False) -> Path

Gets the internal path to an image or thumbnail.

Parameters:

Name	Type	Description	Default
`image_name`	`str`	The name of the image to get the path of.	required
`thumbnail`	`bool`	Get the path of the thumbnail instead of the full image	`False`

Returns:

Type	Description
`Path`	The local path of the image or thumbnail.

get_pil #

get_pil(image_name: str, mode: IMAGE_MODES | None = None) -> Image

Gets an image as a PIL Image object.

Parameters:

Name	Type	Description	Default
`image_name`	`str`	The name of the image to get.	required
`mode`	`IMAGE_MODES \| None`	The color mode to convert the image to. If None, the original mode is used.	`None`

Returns:

Type	Description
`Image`	The image as a PIL Image object.

save #

save(image: Image, board_id: Optional[str] = None, image_category: ImageCategory = ImageCategory.GENERAL, metadata: Optional[MetadataField] = None) -> ImageDTO

Saves an image, returning its DTO.

If the current queue item has a workflow or metadata, it is automatically saved with the image.

Parameters:

Name	Type	Description	Default
`image`	`Image`	The image to save, as a PIL image.	required
`board_id`	`Optional[str]`	The board ID to add the image to, if it should be added. It the invocation inherits from `WithBoard`, that board will be used automatically. Use this only if you want to override or provide a board manually!	`None`
`image_category`	`ImageCategory`	The category of the image. Only the GENERAL category is added to the gallery.	`GENERAL`
`metadata`	`Optional[MetadataField]`	The metadata to save with the image, if it should have any. If the invocation inherits from `WithMetadata`, that metadata will be used automatically. Use this only if you want to override or provide metadata manually!	`None`

Returns:

Type	Description
`ImageDTO`	The saved image DTO.

TensorsInterface #

load #

load(name: str) -> Tensor

Loads a tensor by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the tensor to load.	required

Returns:

Type	Description
`Tensor`	The loaded tensor.

save #

save(tensor: Tensor) -> str

Saves a tensor, returning its name.

Parameters:

Name	Type	Description	Default
`tensor`	`Tensor`	The tensor to save.	required

Returns:

Type	Description
`str`	The name of the saved tensor.

ConditioningInterface #

load #

load(name: str) -> ConditioningFieldData

Loads conditioning data by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the conditioning data to load.	required

Returns:

Type	Description
`ConditioningFieldData`	The loaded conditioning data.

save #

save(conditioning_data: ConditioningFieldData) -> str

Saves a conditioning data object, returning its name.

Parameters:

Name	Type	Description	Default
`conditioning_data`	`ConditioningFieldData`	The conditioning data to save.	required

Returns:

Type	Description
`str`	The name of the saved conditioning data.

ModelsInterface #

exists #

exists(identifier: Union[str, ModelIdentifierField]) -> bool

Checks if a model exists.

Parameters:

Name	Type	Description	Default
`identifier`	`Union[str, ModelIdentifierField]`	The key or ModelField representing the model.	required

Returns:

Type	Description
`bool`	True if the model exists, False if not.

get_config #

get_config(identifier: Union[str, ModelIdentifierField]) -> AnyModelConfig

Gets a model's config.

Parameters:

Name	Type	Description	Default
`identifier`	`Union[str, ModelIdentifierField]`	The key or ModelField representing the model.	required

Returns:

Type	Description
`AnyModelConfig`	The model's config.

load #

load(identifier: Union[str, ModelIdentifierField], submodel_type: Optional[SubModelType] = None) -> LoadedModel

Loads a model.

Parameters:

Name	Type	Description	Default
`identifier`	`Union[str, ModelIdentifierField]`	The key or ModelField representing the model.	required
`submodel_type`	`Optional[SubModelType]`	The submodel of the model to get.	`None`

Returns:

Type	Description
`LoadedModel`	An object representing the loaded model.

load_by_attrs #

load_by_attrs(name: str, base: BaseModelType, type: ModelType, submodel_type: Optional[SubModelType] = None) -> LoadedModel

Loads a model by its attributes.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the model.	required
`base`	`BaseModelType`	The models' base type, e.g. `BaseModelType.StableDiffusion1`, `BaseModelType.StableDiffusionXL`, etc.	required
`type`	`ModelType`	Type of the model, e.g. `ModelType.Main`, `ModelType.Vae`, etc.	required
`submodel_type`	`Optional[SubModelType]`	The type of submodel to load, e.g. `SubModelType.UNet`, `SubModelType.TextEncoder`, etc. Only main	`None`

Returns:

Type	Description
`LoadedModel`	An object representing the loaded model.

search_by_attrs #

search_by_attrs(name: Optional[str] = None, base: Optional[BaseModelType] = None, type: Optional[ModelType] = None, format: Optional[ModelFormat] = None) -> list[AnyModelConfig]

Searches for models by attributes.

Parameters:

Name	Type	Description	Default
`name`	`Optional[str]`	The name to search for (exact match).	`None`
`base`	`Optional[BaseModelType]`	The base to search for, e.g. `BaseModelType.StableDiffusion1`, `BaseModelType.StableDiffusionXL`, etc.	`None`
`type`	`Optional[ModelType]`	Type type of model to search for, e.g. `ModelType.Main`, `ModelType.Vae`, etc.	`None`
`format`	`Optional[ModelFormat]`	The format of model to search for, e.g. `ModelFormat.Checkpoint`, `ModelFormat.Diffusers`, etc.	`None`

Returns:

Type	Description
`list[AnyModelConfig]`	A list of models that match the attributes.

search_by_path #

search_by_path(path: Path) -> list[AnyModelConfig]

Searches for models by path.

Parameters:

Name	Type	Description	Default
`path`	`Path`	The path to search for.	required

Returns:

Type	Description
`list[AnyModelConfig]`	A list of models that match the path.

LoggerInterface #

debug #

debug(message: str) -> None

Logs a debug message.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to log.	required

error #

error(message: str) -> None

Logs an error message.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to log.	required

info #

info(message: str) -> None

Logs an info message.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to log.	required

warning #

warning(message: str) -> None

Logs a warning message.

Parameters:

Name	Type	Description	Default
`message`	`str`	The message to log.	required

ConfigInterface #

get #

get() -> InvokeAIAppConfig

Gets the app's config.

Returns:

Type	Description
`InvokeAIAppConfig`	The app's config.

UtilInterface #

is_canceled #

is_canceled() -> bool

Checks if the current session has been canceled.

Returns:

Type	Description
`bool`	True if the current session has been canceled, False if not.

sd_step_callback #

sd_step_callback(intermediate_state: PipelineIntermediateState, base_model: BaseModelType) -> None

The step callback emits a progress event with the current step, the total number of steps, a preview image, and some other internal metadata.

This should be called after each denoising step.

Parameters:

Name	Type	Description	Default
`intermediate_state`	`PipelineIntermediateState`	The intermediate state of the diffusion pipeline.	required
`base_model`	`BaseModelType`	The base model for the current denoising step.	required

BoardsInterface #

add_image_to_board #

add_image_to_board(board_id: str, image_name: str) -> None

Adds an image to a board.

Parameters:

Name	Type	Description	Default
`board_id`	`str`	The ID of the board to add the image to.	required
`image_name`	`str`	The name of the image to add to the board.	required

create #

create(board_name: str) -> BoardDTO

Creates a board.

Parameters:

Name	Type	Description	Default
`board_name`	`str`	The name of the board to create.	required

Returns:

Type	Description
`BoardDTO`	The created board DTO.

get_all #

get_all() -> list[BoardDTO]

Gets all boards.

Returns:

Type	Description
`list[BoardDTO]`	A list of all boards.

get_all_image_names_for_board #

get_all_image_names_for_board(board_id: str) -> list[str]

Gets all image names for a board.

Parameters:

Name	Type	Description	Default
`board_id`	`str`	The ID of the board to get the image names for.	required

Returns:

Type	Description
`list[str]`	A list of all image names for the board.

get_dto #

get_dto(board_id: str) -> BoardDTO

Gets a board DTO.

Parameters:

Name	Type	Description	Default
`board_id`	`str`	The ID of the board to get.	required

Returns:

Type	Description
`BoardDTO`	The board DTO.

Invocation API#

Invocation Mixins#

WithMetadata#

WithBoard#

InvocationContext #

ImagesInterface #

get_dto #

get_metadata #

get_path #

get_pil #

save #

TensorsInterface #

load #

save #

ConditioningInterface #

load #

save #

ModelsInterface #

exists #

get_config #

load #

load_by_attrs #

search_by_attrs #

search_by_path #

LoggerInterface #

debug #

error #

info #

warning #

ConfigInterface #

get #

UtilInterface #

is_canceled #

sd_step_callback #

BoardsInterface #

add_image_to_board #

create #

get_all #

get_all_image_names_for_board #

get_dto #

`WithMetadata`#

`WithBoard`#