> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jakan.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Operations

> Operations for managing images.

Operations for managing images.

Bases: `StashClientProtocol`

Mixin for image-related client methods.

## Functions

### find\_image

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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

```python theme={null}
bulk_image_update(
    input_data: BulkImageUpdateInput | dict[str, Any],
) -> list[Image]
```

```python theme={null}
bulk_image_update(
    input_data: BulkImageUpdateInput | dict[str, Any],
    *,
    return_fields: str,
) -> list[dict[str, Any]]
```

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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:

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

### image\_increment\_o

```python theme={null}
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 |

<Note>
  **Example**

  ```python theme={null}
  new_count = await client.image_increment_o("123")
  print(f"New O-count: {new_count}")
  ```
</Note>

### image\_decrement\_o

```python theme={null}
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 |

<Note>
  **Example**

  ```python theme={null}
  new_count = await client.image_decrement_o("123")
  print(f"New O-count: {new_count}")
  ```
</Note>

### image\_reset\_o

```python theme={null}
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) |

<Note>
  **Example**

  ```python theme={null}
  count = await client.image_reset_o("123")
  print(f"O-count reset to: {count}")
  ```
</Note>