Performer Operations - Stash Tools & Scrapers

Operations for managing performers (actors/models). Bases: StashClientProtocol Mixin for performer-related client methods.

Functions

find_performer

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:

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

Find by name:

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

Find by filter:

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

Access performer relationships:

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

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:

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:

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

Find performers with high rating and sort by name:

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

Paginate results:

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

create_performer

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:

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

Create performer with metadata:

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:

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

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:

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:

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:

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:

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

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:

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:

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

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:

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

Using the input type:

from ...types import PerformerDestroyInput

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

performers_destroy

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:

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

all_performers

all_performers() -> list[Performer]

Get all performers.

bulk_performer_update

bulk_performer_update(
    input_data: BulkPerformerUpdateInput | dict[str, Any],
) -> list[Performer]

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

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:

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

Add tags to multiple performers:

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

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:

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

Merge with overrides:

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

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:

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

Auto-create missing performers:

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

Handle multiple matches:

performer_ids = await client.map_performer_ids(
    ["AmbiguousName"],
    on_multiple=OnMultipleMatch.RETURN_NONE  # Skip ambiguous matches
)

Use in scene creation:

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)

​Functions

​find_performer

​find_performers

​create_performer

​update_performer

​update_performer_image

​performer_destroy

​performers_destroy

​all_performers

​bulk_performer_update

​performer_merge

​map_performer_ids

Functions

find_performer

find_performers

create_performer

update_performer

update_performer_image

performer_destroy

performers_destroy

all_performers

bulk_performer_update

performer_merge

map_performer_ids