Skip to main content

​
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

Preset Families

Built-in families available to every account, ready to use immediately. No setup required: just pick one and reference its slug.

Custom Families

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.
Custom families can also be shared with your active organization, making them visible (but not deletable) to teammates via List Families and 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 returns a task_id you poll via Get Task, or a webhook you can subscribe to with webhook_url. See Async Processing and Webhooks.
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 and create a new one.

​
Using a Family in a Video

Pass a family’s identifier as selected_family_id on Create Living Property Video. 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):
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.
Using a family does not change the credit cost of the video.
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, Update Family Member, Regenerate Family Member Portrait, and 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
  • 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. This requires a Pro, Max, or Enterprise plan, like all other family write operations. Deleting a family:
  • Removes it from 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

List Families

Browse preset and custom families

Create Family

Create a custom family with AI-generated avatars

Get Family

Check a family’s generation status

Delete Family

Remove a family you own

Add Family Member

Add a new member to an existing family

Update Family Member

Change a member’s descriptors and regenerate their portrait

Regenerate Family Member Portrait

Get a new portrait for a member with the same descriptors

Remove Family Member

Remove a member from a family

Create Living Property Video

Use selected_family_id for a consistent cast