Image Operations - Stash Tools & Scrapers

Operations for managing images. Bases: StashClientProtocol Mixin for image-related client methods.

Functions

find_image

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

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

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

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

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

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

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

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

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

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

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}")

​Functions

​find_image

​find_images

​create_image

​update_image

​image_destroy

​images_destroy

​bulk_image_update

​images_update

​image_increment_o

​image_decrement_o

​image_reset_o

Functions

find_image

find_images

create_image

update_image

image_destroy

images_destroy

bulk_image_update

images_update

image_increment_o

image_decrement_o

image_reset_o