Image Operations

Operations for managing images.

Bases: StashClientProtocol

Mixin for image-related client methods.

Functions

find_image async

find_image(id: str) -> Image | None

Find an image by its ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the image to find	required

Returns:

Type	Description
Image | None	Image object if found, None otherwise

find_images async

find_images(
    filter_: dict[str, Any] | None = None,
    image_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindImagesResultType

Find images matching the given filters.

Parameters:

Name	Type	Description	Default
filter_	dict[str, Any] | None	Optional general filter parameters: - q: str (search query) - direction: SortDirectionEnum (ASC/DESC) - page: int - per_page: int - sort: str (field to sort by)	None
image_filter	dict[str, Any] | None	Optional image-specific filter	None
q	str | None	Optional search query (alternative to filter_["q"])	None

Returns:

Type	Description
FindImagesResultType	FindImagesResultType.

create_image async

create_image(image: Image) -> Image

Create a new image in Stash.

Parameters:

Name	Type	Description	Default
image	Image	Image object with the data to create. Required fields: - title: Image title	required

Returns:

Type	Description
Image	Created Image object with ID and any server-generated fields

Raises:

Type	Description
ValueError	If the image data is invalid
TransportError	If the request fails

update_image async

update_image(image: Image) -> Image

Update an existing image in Stash.

Parameters:

Name	Type	Description	Default
image	Image	Image object with updated data. Required fields: - id: Image ID to update Any other fields that are set will be updated. Fields that are None will be ignored.	required

Returns:

Type	Description
Image	Updated Image object with any server-generated fields

Raises:

Type	Description
ValueError	If the image data is invalid
TransportError	If the request fails

image_destroy async

image_destroy(
    input_data: ImageDestroyInput | dict[str, Any],
) -> bool

Delete an image.

Parameters:

Name	Type	Description	Default
input_data	ImageDestroyInput | dict[str, Any]	ImageDestroyInput object or dictionary.	required

Returns:

Type	Description
bool	True if the image was successfully deleted

Raises:

Type	Description
ValueError	If the image ID is invalid
TransportError	If the request fails

images_destroy async

images_destroy(
    input_data: ImagesDestroyInput | dict[str, Any],
) -> bool

Delete multiple images.

Parameters:

Name	Type	Description	Default
input_data	ImagesDestroyInput | dict[str, Any]	ImagesDestroyInput object or dictionary.	required

Returns:

Type	Description
bool	True if the images were successfully deleted

Raises:

Type	Description
ValueError	If any image ID is invalid
TransportError	If the request fails

bulk_image_update async

bulk_image_update(
    input_data: BulkImageUpdateInput | dict[str, Any],
) -> list[Image]

bulk_image_update(
    input_data: BulkImageUpdateInput | dict[str, Any],
    *,
    return_fields: str,
) -> list[dict[str, Any]]

bulk_image_update(
    input_data: BulkImageUpdateInput | dict[str, Any],
    *,
    return_fields: str | None = None,
) -> list[Image] | list[dict[str, Any]]

Bulk update images.

Parameters:

Name	Type	Description	Default
input_data	BulkImageUpdateInput | dict[str, Any]	BulkImageUpdateInput object or dictionary with fields to update.	required
return_fields	str | None	If provided, use a minimal inline mutation requesting only these fields (e.g. "id"). Avoids the full fragment response, which is significantly faster for fire-and-forget bulk updates. When set, returns a list of raw dicts instead of Image objects.	None

Returns:

Type	Description
list[Image] | list[dict[str, Any]]	List of updated Image objects (default), or list of dicts when
list[Image] | list[dict[str, Any]]	return_fields is provided.

images_update async

images_update(
    updates: list[ImageUpdateInput] | list[dict[str, Any]],
) -> list[Image]

Update multiple images with individual update data.

This is different from bulk_image_update which applies the same updates to all images. This method allows updating each image with different values.

Parameters:

Name	Type	Description	Default
updates	list[ImageUpdateInput] | list[dict[str, Any]]	List of ImageUpdateInput objects or dictionaries, each containing: - id: Image ID to update (required) - Any other fields to update for that specific image	required

Returns:

Type	Description
list[Image]	List of updated Image objects (may contain None for failed updates)

Examples:

Update multiple images with different values:

from stash_graphql_client.types import ImageUpdateInput

updates = [
    ImageUpdateInput(id="1", title="First Image", organized=True),
    ImageUpdateInput(id="2", title="Second Image", rating100=90),
]
images = await client.images_update(updates)

Using dictionaries:

updates = [
    {"id": "1", "organized": True},
    {"id": "2", "rating100": 75},
]
images = await client.images_update(updates)

image_increment_o async

image_increment_o(id: str) -> int

Increment the O-counter for an image.

Parameters:

Name	Type	Description	Default
id	str	Image ID	required

Returns:

Type	Description
int	New O-count value after incrementing

Example

new_count = await client.image_increment_o("123")
print(f"New O-count: {new_count}")

image_decrement_o async

image_decrement_o(id: str) -> int

Decrement the O-counter for an image.

Parameters:

Name	Type	Description	Default
id	str	Image ID	required

Returns:

Type	Description
int	New O-count value after decrementing

Example

new_count = await client.image_decrement_o("123")
print(f"New O-count: {new_count}")

image_reset_o async

image_reset_o(id: str) -> int

Reset the O-counter for an image to 0.

Parameters:

Name	Type	Description	Default
id	str	Image ID	required

Returns:

Type	Description
int	New O-count value (0)

Example

count = await client.image_reset_o("123")
print(f"O-count reset to: {count}")