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

# Families

> Reusable, consistent casts of people for your real estate videos

# Families

A **family** is a reusable cast of AI-generated people that stays consistent across every scene of a real estate video. Instead of the AI casting different people in each room, you point a video at a family and the same faces show up throughout: a father in the kitchen is the same father you see in the living room.

## Preset vs. Custom Families

<CardGroup cols={2}>
  <Card title="Preset Families" icon="users">
    Built-in families available to every account, ready to use immediately. No setup required: just pick one and reference its `slug`.
  </Card>

  <Card title="Custom Families" icon="user-plus">
    Families you create with your own choice of members (type, role, age, ethnicity, physical description, clothing). Avatars are generated by AI once, then reused across as many videos as you like.
  </Card>
</CardGroup>

Custom families can also be shared with your active organization, making them visible (but not deletable) to teammates via [List Families](/api-reference/families/list-families) and [Get Family](/api-reference/families/get-family).

## Creating a Custom Family

Creating a family requires a **Pro**, **Max**, or **Enterprise** plan, and is always **free**: 0 credits, regardless of how many members you add. You can have up to **5** active custom families at a time; families shared with you by an organization don't count against this limit.

A family has between **1 and 6 members**. Each member has a `type` (`adult`, `child`, or `senior`) and an optional `role` (e.g. `father`, `mother`, `daughter`) plus optional descriptive fields (`age`, `ethnicity`, `physical`, `clothing`) that guide avatar generation.

Avatar generation is asynchronous, just like video generation: [Create Family](/api-reference/families/create-family) returns a `task_id` you poll via [Get Task](/api-reference/videos/get-task), or a webhook you can subscribe to with `webhook_url`. See [Async Processing](/concepts/async-processing) and [Webhooks](/concepts/webhooks).

<Warning>
  **A family that ends up `failed` or `pending_avatars` cannot be repaired.**
  Every member operation on it returns `422 FAMILY_NOT_READY`, and there is no
  endpoint that re-runs generation for an existing family. It also still counts
  against your family limit. The only way forward is to
  [delete it](/api-reference/families/delete-family) and create a new one.
</Warning>

## Using a Family in a Video

Pass a family's identifier as `selected_family_id` on [Create Living Property Video](/api-reference/videos/create-living-property). Use the `id` for a family you own or that's shared by your organization, or the `slug` for a preset (browse them all in the [preset gallery](/api-reference/families/preset-families)):

```json theme={null}
{
  "images": ["..."],
  "voice": { "voice_id": "EXAVITQu4vr4xnSDxMaL", "language": "en" },
  "modification_mode": "no_modify",
  "script": "Welcome to this stunning modern home...",
  "selected_family_id": "family-with-kids"
}
```

The family must be:

* A **preset**, or **yours**, or **shared by your organization**
* In `ready` status: a family that's still `generating`, `pending_avatars`, or `failed` is rejected with `FAMILY_NOT_READY`

**Using a family, whether a preset or one of your own, requires a Pro, Max, or Enterprise plan.** A request on a lower plan is rejected with `403 PLAN_NOT_ALLOWED`. This is separate from the plan required to create or edit a family: listing and reading families doesn't require any particular plan.

Omitting `selected_family_id` leaves casting behavior unchanged from today: the AI casts people per scene as usual.

<Note>
  Using a family does not change the credit cost of the video.
</Note>

Scenes vary naturally: family members can appear in different combinations and counts from one scene to the next, always drawn from the same cast.

## Editing a Family

Owners can adjust a custom family's cast after creation, via [Add Family Member](/api-reference/families/add-family-member), [Update Family Member](/api-reference/families/update-family-member), [Regenerate Family Member Portrait](/api-reference/families/regenerate-family-member), and [Remove Family Member](/api-reference/families/remove-family-member). Each of these:

* Requires the **Pro**, **Max**, or **Enterprise** plan, like using a family in a video
* Only works while the family is `ready`: another edit already in progress rejects the request with `422 FAMILY_NOT_READY`, since only one generation can run for a family at a time. Wait by polling the `task_id` the edit returned, or by polling the family until its `status` returns to `ready`
* Keeps the family between **1 and 6** members: adding past the limit returns `422 FAMILY_MEMBER_LIMIT_EXCEEDED`, and removing the last member returns `422 FAMILY_MEMBER_MINIMUM`
* Regenerates the affected member's portrait and the family's group `card_image_url`, and returns a `task_id` you poll (or a webhook) the same way as [Create Family](/api-reference/families/create-family)
* Leaves the family **exactly as it was** if the operation fails: no partial changes are ever persisted

## Deleting a Family

Only the owner can delete a family, via [Delete Family](/api-reference/families/delete-family). This requires a **Pro**, **Max**, or **Enterprise** plan, like all other family write operations. Deleting a family:

* Removes it from [List Families](/api-reference/families/list-families) and makes it unusable as `selected_family_id` in new videos
* Does **not** affect videos you already generated with it; their results stay available

## Next Steps

<CardGroup cols={2}>
  <Card title="List Families" icon="list" href="/api-reference/families/list-families">
    Browse preset and custom families
  </Card>

  <Card title="Create Family" icon="user-plus" href="/api-reference/families/create-family">
    Create a custom family with AI-generated avatars
  </Card>

  <Card title="Get Family" icon="magnifying-glass" href="/api-reference/families/get-family">
    Check a family's generation status
  </Card>

  <Card title="Delete Family" icon="trash" href="/api-reference/families/delete-family">
    Remove a family you own
  </Card>

  <Card title="Add Family Member" icon="user-plus" href="/api-reference/families/add-family-member">
    Add a new member to an existing family
  </Card>

  <Card title="Update Family Member" icon="pen" href="/api-reference/families/update-family-member">
    Change a member's descriptors and regenerate their portrait
  </Card>

  <Card title="Regenerate Family Member Portrait" icon="arrows-rotate" href="/api-reference/families/regenerate-family-member">
    Get a new portrait for a member with the same descriptors
  </Card>

  <Card title="Remove Family Member" icon="user-minus" href="/api-reference/families/remove-family-member">
    Remove a member from a family
  </Card>

  <Card title="Create Living Property Video" icon="house" href="/api-reference/videos/create-living-property">
    Use `selected_family_id` for a consistent cast
  </Card>
</CardGroup>