> ## 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.

# Performer Operations

> Operations for managing performers (actors/models).

Operations for managing performers (actors/models).

Bases: `StashClientProtocol`

Mixin for performer-related client methods.

## Functions

### find\_performer

```python theme={null}
find_performer(
    performer: int | str | dict,
) -> Performer | None
```

Find a performer by ID, name, or filter.

Parameters:

| Name        | Type                 | Description                                                                                   | Default    |
| ----------- | -------------------- | --------------------------------------------------------------------------------------------- | ---------- |
| `performer` | `int \| str \| dict` | Can be: - ID (int/str): Find by ID - Name (str): Find by name - Dict: Find by filter criteria | *required* |

Returns:

| Type                | Description                               |
| ------------------- | ----------------------------------------- |
| `Performer \| None` | Performer object if found, None otherwise |

Examples:

Find by ID:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    print(f"Found performer: {performer.name}")
```

Find by name:

```python theme={null}
performer = await client.find_performer("Performer Name")
if performer:
    print(f"Found performer with ID: {performer.id}")
```

Find by filter:

```python theme={null}
performer = await client.find_performer({
    "name": "Performer Name",
    "disambiguation": "2000s"
})
```

Access performer relationships:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    # Get scene titles
    scene_titles = [s.title for s in performer.scenes]
    # Get studio name
    studio_name = performer.studio.name if performer.studio else None
    # Get tag names
    tags = [t.name for t in performer.tags]
```

### find\_performers

```python theme={null}
find_performers(
    filter_: dict[str, Any] | None = None,
    performer_filter: dict[str, Any] | None = None,
    q: str | None = None,
) -> FindPerformersResultType
```

Find performers 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`  |
| `q`                | `str \| None`            | Optional search query (alternative to filter\_\["q"])                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `None`  |
| `performer_filter` | `dict[str, Any] \| None` | Optional performer-specific filter: - birth\_year: IntCriterionInput - age: IntCriterionInput - ethnicity: StringCriterionInput - country: StringCriterionInput - eye\_color: StringCriterionInput - height: StringCriterionInput - measurements: StringCriterionInput - fake\_tits: StringCriterionInput - career\_length: StringCriterionInput - tattoos: StringCriterionInput - piercings: StringCriterionInput - favorite: bool - rating100: IntCriterionInput - gender: GenderEnum - is\_missing: str (what data is missing) - name: StringCriterionInput - studios: HierarchicalMultiCriterionInput - tags: HierarchicalMultiCriterionInput | `None`  |

Returns:

| Type                       | Description                                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `FindPerformersResultType` | FindPerformersResultType containing: - count: Total number of matching performers - performers: List of Performer objects |

Examples:

Find all favorite performers:

```python theme={null}
result = await client.find_performers(
    performer_filter={"favorite": True}
)
print(f"Found {result.count} favorite performers")
for performer in result.performers:
    print(f"- {performer.name}")
```

Find performers with specific tags:

```python theme={null}
result = await client.find_performers(
    performer_filter={
        "tags": {
            "value": ["tag1", "tag2"],
            "modifier": "INCLUDES_ALL"
        }
    }
)
```

Find performers with high rating and sort by name:

```python theme={null}
result = await client.find_performers(
    filter_={
        "direction": "ASC",
        "sort": "name",
    },
    performer_filter={
        "rating100": {
            "value": 80,
            "modifier": "GREATER_THAN"
        }
    }
)
```

Paginate results:

```python theme={null}
result = await client.find_performers(
    filter_={
        "page": 1,
        "per_page": 25,
    }
)
```

### create\_performer

```python theme={null}
create_performer(performer: Performer) -> Performer
```

Create a new performer in Stash.

Parameters:

| Name        | Type        | Description                                                                       | Default    |
| ----------- | ----------- | --------------------------------------------------------------------------------- | ---------- |
| `performer` | `Performer` | Performer object with the data to create. Required fields: - name: Performer name | *required* |

Returns:

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

Raises:

| Type             | Description                      |
| ---------------- | -------------------------------- |
| `ValueError`     | If the performer data is invalid |
| `TransportError` | If the request fails             |

Examples:

Create a basic performer:

```python theme={null}
performer = Performer(
    name="Performer Name",
)
created = await client.create_performer(performer)
print(f"Created performer with ID: {created.id}")
```

Create performer with metadata:

```python theme={null}
performer = Performer(
    name="Performer Name",
    # Add metadata
    gender="FEMALE",
    birthdate="1990-01-01",
    ethnicity="Caucasian",
    country="USA",
    eye_color="Blue",
    height_cm=170,
    measurements="34B-24-36",
    fake_tits="No",
    career_length="2010-2020",
    tattoos="None",
    piercings="Ears",
    url="https://example.com/performer",
    twitter="@performer",
    instagram="@performer",
    details="Performer details",
)
created = await client.create_performer(performer)
```

Create performer with relationships:

```python theme={null}
performer = Performer(
    name="Performer Name",
    # Add relationships
    tags=[tag1, tag2],
    image="https://example.com/image.jpg",
    stash_ids=[stash_id1, stash_id2],
)
created = await client.create_performer(performer)
```

### update\_performer

```python theme={null}
update_performer(performer: Performer) -> Performer
```

Update an existing performer in Stash.

Parameters:

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

Returns:

| Type        | Description                                               |
| ----------- | --------------------------------------------------------- |
| `Performer` | Updated Performer object with any server-generated fields |

Raises:

| Type             | Description                      |
| ---------------- | -------------------------------- |
| `ValueError`     | If the performer data is invalid |
| `TransportError` | If the request fails             |

Examples:

Update performer name and metadata:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    performer.name = "New Name"
    performer.gender = "FEMALE"
    performer.birthdate = "1990-01-01"
    updated = await client.update_performer(performer)
    print(f"Updated performer: {updated.name}")
```

Update performer relationships:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    # Add new tags
    performer.tags.extend([new_tag1, new_tag2])
    # Update image
    performer.image = "https://example.com/new-image.jpg"
    updated = await client.update_performer(performer)
```

Update performer URLs:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    # Replace URLs
    performer.url = "https://example.com/new-url"
    performer.twitter = "@new_twitter"
    performer.instagram = "@new_instagram"
    updated = await client.update_performer(performer)
```

Remove performer relationships:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    # Clear tags
    performer.tags = []
    # Clear image
    performer.image = None
    updated = await client.update_performer(performer)
```

### update\_performer\_image

```python theme={null}
update_performer_image(
    performer: Performer, image_url: str
) -> Performer
```

Update a performer's image.

Parameters:

| Name        | Type        | Description                               | Default    |
| ----------- | ----------- | ----------------------------------------- | ---------- |
| `performer` | `Performer` | Performer object with at least the ID set | *required* |
| `image_url` | `str`       | URL or data URI of the image to set       | *required* |

Returns:

| Type        | Description                                 |
| ----------- | ------------------------------------------- |
| `Performer` | Updated Performer object with the new image |

Raises:

| Type             | Description                      |
| ---------------- | -------------------------------- |
| `ValueError`     | If the performer data is invalid |
| `TransportError` | If the request fails             |

Examples:

Update performer image with a data URI:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    # Update with data URI
    image_url = "data:image/jpeg;base64,..."
    updated = await client.update_performer_image(performer, image_url)
```

Update performer image from a file:

```python theme={null}
performer = await client.find_performer("123")
if performer:
    # Use the performer's update_avatar method
    updated = await performer.update_avatar(client, "/path/to/image.jpg")
```

### performer\_destroy

```python theme={null}
performer_destroy(
    input_data: PerformerDestroyInput | dict[str, Any],
) -> bool
```

Delete a performer.

Parameters:

| Name         | Type                                      | Description                                 | Default    |
| ------------ | ----------------------------------------- | ------------------------------------------- | ---------- |
| `input_data` | `PerformerDestroyInput \| dict[str, Any]` | PerformerDestroyInput object or dictionary. | *required* |

Returns:

| Type   | Description                                    |
| ------ | ---------------------------------------------- |
| `bool` | True if the performer was successfully deleted |

Raises:

| Type             | Description                    |
| ---------------- | ------------------------------ |
| `ValueError`     | If the performer ID is invalid |
| `TransportError` | If the request fails           |

Examples:

Delete a performer:

```python theme={null}
result = await client.performer_destroy({"id": "123"})
print(f"Performer deleted: {result}")
```

Using the input type:

```python theme={null}
from ...types import PerformerDestroyInput

input_data = PerformerDestroyInput(id="123")
result = await client.performer_destroy(input_data)
```

### performers\_destroy

```python theme={null}
performers_destroy(ids: list[str]) -> bool
```

Delete multiple performers.

Parameters:

| Name  | Type        | Description                     | Default    |
| ----- | ----------- | ------------------------------- | ---------- |
| `ids` | `list[str]` | List of performer IDs to delete | *required* |

Returns:

| Type   | Description                                      |
| ------ | ------------------------------------------------ |
| `bool` | True if the performers were successfully deleted |

Raises:

| Type             | Description                    |
| ---------------- | ------------------------------ |
| `ValueError`     | If any performer ID is invalid |
| `TransportError` | If the request fails           |

Examples:

Delete multiple performers:

```python theme={null}
result = await client.performers_destroy(["123", "456", "789"])
print(f"Performers deleted: {result}")
```

### all\_performers

```python theme={null}
all_performers() -> list[Performer]
```

Get all performers.

### bulk\_performer\_update

```python theme={null}
bulk_performer_update(
    input_data: BulkPerformerUpdateInput | dict[str, Any],
) -> list[Performer]
```

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

```python theme={null}
bulk_performer_update(
    input_data: BulkPerformerUpdateInput | dict[str, Any],
    *,
    return_fields: str | None = None,
) -> list[Performer] | list[dict[str, Any]]
```

Bulk update performers.

Parameters:

| Name         | Type                                         | Description                                                          | Default    |
| ------------ | -------------------------------------------- | -------------------------------------------------------------------- | ---------- |
| `input_data` | `BulkPerformerUpdateInput \| dict[str, Any]` | BulkPerformerUpdateInput object or dictionary with fields to update. | *required* |

Returns:

| Type                                      | Description                       |
| ----------------------------------------- | --------------------------------- |
| `list[Performer] \| list[dict[str, Any]]` | List of updated Performer objects |

Examples:

Update multiple performers' gender:

```python theme={null}
performers = await client.bulk_performer_update({
    "ids": ["1", "2", "3"],
    "gender": "FEMALE"
})
```

Add tags to multiple performers:

```python theme={null}
from stash_graphql_client.types import BulkPerformerUpdateInput, BulkUpdateIds

input_data = BulkPerformerUpdateInput(
    ids=["1", "2", "3"],
    tag_ids=BulkUpdateIds(ids=["tag1", "tag2"], mode="ADD")
)
performers = await client.bulk_performer_update(input_data)
```

### performer\_merge

```python theme={null}
performer_merge(
    input_data: PerformerMergeInput | dict[str, Any],
) -> Performer
```

Merge performers into a single performer.

**Minimum Stash Version**: v0.30.2+ or commit `65e82a0` or newer

This feature requires Stash v0.30.2 or later (or development builds with commit 65e82a0+). Older Stash versions will raise a GraphQL error.

Parameters:

| Name         | Type                                    | Description                               | Default    |
| ------------ | --------------------------------------- | ----------------------------------------- | ---------- |
| `input_data` | `PerformerMergeInput \| dict[str, Any]` | PerformerMergeInput object or dictionary. | *required* |

Returns:

| Type        | Description                 |
| ----------- | --------------------------- |
| `Performer` | The merged Performer object |

Raises:

| Type                | Description                                |
| ------------------- | ------------------------------------------ |
| `StashGraphQLError` | If Stash version is too old or merge fails |

Examples:

Merge performers:

```python theme={null}
merged = await client.performer_merge({
    "source": ["performer1-id", "performer2-id"],
    "destination": "destination-performer-id"
})
```

Merge with overrides:

```python theme={null}
from stash_graphql_client.types import PerformerMergeInput, PerformerUpdateInput

merged = await client.performer_merge(
    PerformerMergeInput(
        source=["performer1-id", "performer2-id"],
        destination="destination-performer-id",
        values=PerformerUpdateInput(
            id="destination-performer-id",
            name="New Name",
            gender="FEMALE"
        )
    )
)
```

### map\_performer\_ids

```python theme={null}
map_performer_ids(
    performers: list[str | dict[str, Any] | Performer],
    create: bool = False,
    on_multiple: OnMultipleMatch = RETURN_FIRST,
) -> list[str]
```

Convert performer names/objects to IDs, optionally creating missing performers.

This is a convenience method to resolve performer references to their IDs, reducing boilerplate when working with performer relationships.

Parameters:

| Name          | Type                                       | Description                                                                                                                                                                                                                                                            | Default        |
| ------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `performers`  | `list[str \| dict[str, Any] \| Performer]` | List of performer references, can be: - str: Performer name (searches by name, then aliases) - dict: Performer filter criteria (e.g., \{"name": "John", "disambiguation": "Actor"}) - Performer: Performer object (extracts ID if present, otherwise searches by name) | *required*     |
| `create`      | `bool`                                     | If True, create performers that don't exist. Default is False.                                                                                                                                                                                                         | `False`        |
| `on_multiple` | `OnMultipleMatch`                          | Strategy when multiple matches found. Default is RETURN\_FIRST.                                                                                                                                                                                                        | `RETURN_FIRST` |

Returns:

| Type        | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `list[str]` | List of performer IDs. Skips performers that aren't found (unless create=True). |

Examples:

Map performer names to IDs:

```python theme={null}
performer_ids = await client.map_performer_ids(["Jane Doe", "John Smith"])
# Returns: ["1", "2"] (IDs of existing performers)
```

Auto-create missing performers:

```python theme={null}
performer_ids = await client.map_performer_ids(
    ["Jane Doe", "NewPerformer"],
    create=True
)
# Creates "NewPerformer" if it doesn't exist
```

Handle multiple matches:

```python theme={null}
performer_ids = await client.map_performer_ids(
    ["AmbiguousName"],
    on_multiple=OnMultipleMatch.RETURN_NONE  # Skip ambiguous matches
)
```

Use in scene creation:

```python theme={null}
scene = Scene(
    title="My Scene",
    performers=[]  # Will populate with performer IDs
)
scene.performers = await client.map_performer_ids(
    ["Jane Doe", "John Smith"],
    create=True
)
created_scene = await client.create_scene(scene)
```