Gallery Operations - Stash Tools & Scrapers

Operations for managing galleries (image collections). Bases: StashClientProtocol Mixin for gallery-related client methods.

Functions

find_gallery

find_gallery(id: str) -> Gallery | None

Find a gallery by its ID. Parameters:

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

Returns:

Type	Description
`Gallery \| None`	Gallery object if found, None otherwise

find_galleries

find_galleries(
    filter_: dict[str, Any] | None = None,
    gallery_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindGalleriesResultType

Find galleries 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`
`gallery_filter`	`dict[str, Any] \| None`	Optional gallery-specific filter	`None`
`q`	`str \| None`	Optional search query (alternative to filter_[“q”])	`None`

Returns:

Type	Description
`FindGalleriesResultType`	FindGalleriesResultType containing: - count: Total number of matching galleries - galleries: List of Gallery objects

create_gallery

create_gallery(gallery: Gallery) -> Gallery

Create a new gallery in Stash. Parameters:

Name	Type	Description	Default
`gallery`	`Gallery`	Gallery object with the data to create. Required fields: - title: Gallery title	required

Returns:

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

Raises:

Type	Description
`ValueError`	If the gallery data is invalid
`TransportError`	If the request fails

update_gallery

update_gallery(gallery: Gallery) -> Gallery

Update an existing gallery in Stash. Parameters:

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

Returns:

Type	Description
`Gallery`	Updated Gallery object with any server-generated fields

Raises:

Type	Description
`ValueError`	If the gallery data is invalid
`TransportError`	If the request fails

galleries_update

galleries_update(galleries: list[Gallery]) -> list[Gallery]

Update multiple galleries with individual data. Parameters:

Name	Type	Description	Default
`galleries`	`list[Gallery]`	List of Gallery objects to update, each must have an ID	required

Returns:

Type	Description
`list[Gallery]`	List of updated Gallery objects

gallery_destroy

gallery_destroy(
    ids: list[str],
    delete_file: bool | None = None,
    delete_generated: bool | None = None,
) -> bool

Delete galleries. Parameters:

Name	Type	Description	Default
`ids`	`list[str]`	List of gallery IDs to delete	required
`delete_file`	`bool \| None`	If true, delete associated files	`None`
`delete_generated`	`bool \| None`	If true, delete generated files	`None`

Returns:

Type	Description
`bool`	True if successful

remove_gallery_images

remove_gallery_images(
    gallery_id: str, image_ids: list[str]
) -> bool

Remove images from a gallery. Parameters:

Name	Type	Description	Default
`gallery_id`	`str`	Gallery ID	required
`image_ids`	`list[str]`	List of image IDs to remove	required

Returns:

Type	Description
`bool`	True if successful

set_gallery_cover

set_gallery_cover(
    gallery_id: str, cover_image_id: str
) -> bool

Set the cover image for a gallery. Parameters:

Name	Type	Description	Default
`gallery_id`	`str`	Gallery ID	required
`cover_image_id`	`str`	ID of the image to use as cover	required

Returns:

Type	Description
`bool`	True if successful

reset_gallery_cover

reset_gallery_cover(gallery_id: str) -> bool

Reset the cover image for a gallery. Parameters:

Name	Type	Description	Default
`gallery_id`	`str`	Gallery ID	required

Returns:

Type	Description
`bool`	True if successful

gallery_chapter_create

gallery_chapter_create(
    gallery_id: str, title: str, image_index: int
) -> GalleryChapter

Create a new gallery chapter. Parameters:

Name	Type	Description	Default
`gallery_id`	`str`	Gallery ID	required
`title`	`str`	Chapter title	required
`image_index`	`int`	Index of the image where the chapter starts	required

Returns:

Type	Description
`GalleryChapter`	Created GalleryChapter object

gallery_chapter_update

gallery_chapter_update(
    id: str,
    gallery_id: str | None = None,
    title: str | None = None,
    image_index: int | None = None,
) -> GalleryChapter

Update a gallery chapter. Parameters:

Name	Type	Description	Default
`id`	`str`	Chapter ID	required
`gallery_id`	`str \| None`	Optional gallery ID to move chapter to	`None`
`title`	`str \| None`	Optional new title	`None`
`image_index`	`int \| None`	Optional new image index	`None`

Returns:

Type	Description
`GalleryChapter`	Updated GalleryChapter object

add_gallery_images

add_gallery_images(
    gallery_id: str, image_ids: list[str]
) -> bool

Add images to a gallery. Parameters:

Name	Type	Description	Default
`gallery_id`	`str`	Gallery ID	required
`image_ids`	`list[str]`	List of image IDs to add	required

Returns:

Type	Description
`bool`	True if successful

Examples: Add images to a gallery:

success = await client.add_gallery_images(
    gallery_id=gallery.id,
    image_ids=["456", "789"],
)

update_gallery_images

update_gallery_images(
    gallery_id: str, image_ids: list[str], mode: str = "SET"
) -> bool

Update gallery images with the specified mode. This is a convenience method that delegates to either add_gallery_images or remove_gallery_images based on the mode parameter. Parameters:

Name	Type	Description	Default
`gallery_id`	`str`	Gallery ID	required
`image_ids`	`list[str]`	List of image IDs to set, add, or remove	required
`mode`	`str`	Operation mode - “SET”, “ADD”, or “REMOVE” (default: “SET”) - “SET”: Replace all gallery images with the provided list - “ADD”: Add the images to the gallery - “REMOVE”: Remove the images from the gallery	`'SET'`

Returns:

Type	Description
`bool`	True if successful

Raises:

Type	Description
`ValueError`	If mode is not one of “SET”, “ADD”, or “REMOVE”

Examples: Set gallery images (replace all):

success = await client.update_gallery_images(
    gallery_id="123",
    image_ids=["img_1", "img_2"],
    mode="SET",
)

Add images to gallery:

success = await client.update_gallery_images(
    gallery_id="123",
    image_ids=["img_3"],
    mode="ADD",
)

Remove images from gallery:

success = await client.update_gallery_images(
    gallery_id="123",
    image_ids=["img_1"],
    mode="REMOVE",
)

gallery_chapter_destroy

gallery_chapter_destroy(id: str) -> bool

Delete a gallery chapter. Parameters:

Name	Type	Description	Default
`id`	`str`	Chapter ID	required

Returns:

Type	Description
`bool`	True if successful

bulk_gallery_update

bulk_gallery_update(
    input_data: BulkGalleryUpdateInput | dict[str, Any],
) -> list[Gallery]

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

bulk_gallery_update(
    input_data: BulkGalleryUpdateInput | dict[str, Any],
    *,
    return_fields: str | None = None,
) -> list[Gallery] | list[dict[str, Any]]

Bulk update galleries. Parameters:

Name	Type	Description	Default
`input_data`	`BulkGalleryUpdateInput \| dict[str, Any]`	BulkGalleryUpdateInput 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"`). Returns raw dicts instead of Gallery objects.	`None`

Returns:

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

​Functions

​find_gallery

​find_galleries

​create_gallery

​update_gallery

​galleries_update

​gallery_destroy

​remove_gallery_images

​set_gallery_cover

​reset_gallery_cover

​gallery_chapter_create

​gallery_chapter_update

​add_gallery_images

​update_gallery_images

​gallery_chapter_destroy

​bulk_gallery_update

Functions

find_gallery

find_galleries

create_gallery

update_gallery

galleries_update

gallery_destroy

remove_gallery_images

set_gallery_cover

reset_gallery_cover

gallery_chapter_create

gallery_chapter_update

add_gallery_images

update_gallery_images

gallery_chapter_destroy

bulk_gallery_update