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

# List Families

> Retrieve the list of families available for casting in real estate videos

Retrieves the list of families. A family is a reusable cast of AI-generated people that keeps the same faces consistent across every scene of a real estate video. The list includes built-in **preset** families available to everyone, plus any **custom** families you own or that have been shared by your active organization.

## Query Parameters

<ParamField query="type" type="string" default="all">
  The type of families to retrieve.

  **Allowed values:** `preset`, `custom`, `all`

  * `preset`: Built-in families available to every account
  * `custom`: Families you own, plus any shared by your active organization
  * `all`: Both preset and custom families (default)
</ParamField>

## Response

<ResponseField name="families" type="array" required>
  List of family objects.

  <Expandable title="Family properties">
    <ResponseField name="families[].id" type="string">
      Unique identifier for the family. Only present for `user`-scope families: use it for the `selected_family_id` parameter when creating a [living property video](/api-reference/videos/create-living-property). Preset families omit `id`; reference them by `slug` instead.
    </ResponseField>

    <ResponseField name="families[].scope" type="string" required>
      `preset` for built-in families available to everyone, or `user` for a family created by an account.
    </ResponseField>

    <ResponseField name="families[].slug" type="string" required>
      Identifier for the family.

      For a **preset** this is a stable, readable slug (e.g. `family-with-kids`)
      and is the value to pass as `selected_family_id`.

      For a **`user`** family this is an opaque generated UUID — not derived from
      the name, not readable, and **not accepted** as an address by
      [Get Family](/api-reference/families/get-family) or `selected_family_id`.
      Address your own families by `id`.
    </ResponseField>

    <ResponseField name="families[].name" type="string | null" required>
      Display name of the family.

      <Warning>
        **Preset families currently return `null` here.** Their display names
        ("Family with kids", "Retired couple", ...) live in the
        [preset gallery](/api-reference/families/preset-families), not in the API
        response. Fall back to the `slug` when rendering a preset, and treat this
        field as nullable.
      </Warning>
    </ResponseField>

    <ResponseField name="families[].members" type="array" required>
      The members that make up this family's cast.

      <Expandable title="Member properties">
        <Note>
          The member shape differs between the two scopes. A `user` family returns
          every descriptor you supplied at creation. A **preset** family returns
          only `role` (carrying the age category, e.g. `adult` / `child`) and
          sometimes `age` — it has **no `type`** field and no other descriptors.
          Don't assume `type` is present when reading a family back.
        </Note>

        <ResponseField name="members[].type" type="string">
          Broad age category: `adult`, `child`, or `senior`.

          Always present on `user` families. **Absent on preset families.**
        </ResponseField>

        <ResponseField name="members[].role" type="string">
          On a `user` family, a short descriptive label for this member's role,
          e.g. `father`, `mother`, `daughter`, `grandmother`.

          On a **preset** family this instead carries the age category
          (`adult` or `child`).
        </ResponseField>

        <ResponseField name="members[].age" type="string">
          Free-text age or age range that guided avatar generation, e.g. `35-40`.
        </ResponseField>

        <ResponseField name="members[].ethnicity" type="string">
          Free-text ethnicity that guided avatar generation.
        </ResponseField>

        <ResponseField name="members[].physical" type="string">
          Free-text physical description that guided avatar generation, e.g. `athletic build, short dark hair`.
        </ResponseField>

        <ResponseField name="members[].clothing" type="string">
          Free-text clothing description that guided avatar generation, e.g. `casual button-down shirt`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="families[].card_image_url" type="string | null" required>
      Preview image showing the full family together. `null` while the family's avatars are still being generated.
    </ResponseField>

    <ResponseField name="families[].reference_image_urls" type="string[]" required>
      Reference image URLs generated for the family's members.
    </ResponseField>

    <ResponseField name="families[].owner_id" type="string | null" required>
      The account that created the family. `null` for preset families.
    </ResponseField>

    <ResponseField name="families[].org_id" type="string | null" required>
      The organization the family is shared with, if any.
    </ResponseField>

    <ResponseField name="families[].created_at" type="string" required>
      Family creation timestamp (ISO 8601 format).
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  # List every family available to the caller
  curl "https://api.vibepeak.ai/v1/families" \
    -H "Authorization: Bearer vpk_live_xxxxx"

  # List only your own (or org-shared) families
  curl "https://api.vibepeak.ai/v1/families?type=custom" \
    -H "Authorization: Bearer vpk_live_xxxxx"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.vibepeak.ai/v1/families', {
    headers: {
      'Authorization': 'Bearer vpk_live_xxxxx'
    }
  });

  const data = await response.json();
  console.log(`Found ${data.families.length} families`);

  for (const family of data.families) {
    console.log(`${family.name} (${family.slug}) - ${family.scope}`);
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.vibepeak.ai/v1/families',
      params={'type': 'all'},
      headers={'Authorization': 'Bearer vpk_live_xxxxx'}
  )

  data = response.json()
  print(f"Found {len(data['families'])} families")

  for family in data['families']:
      print(f"{family['name']} ({family['slug']}) - {family['scope']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 All Families theme={null}
  {
    "families": [
      {
        "scope": "preset",
        "slug": "family-with-kids",
        "name": null,
        "members": [
          { "role": "adult" },
          { "role": "adult" },
          { "role": "child" },
          { "role": "child" }
        ],
        "card_image_url": "https://app.vibepeak.ai/previews/families/family-with-kids/card.png",
        "reference_image_urls": [
          "https://app.vibepeak.ai/previews/families/family-with-kids/member-1.png",
          "https://app.vibepeak.ai/previews/families/family-with-kids/member-2.png",
          "https://app.vibepeak.ai/previews/families/family-with-kids/member-3.png",
          "https://app.vibepeak.ai/previews/families/family-with-kids/member-4.png"
        ],
        "owner_id": null,
        "org_id": null,
        "created_at": "2026-06-30T19:59:51.084814+00:00"
      },
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "scope": "user",
        "slug": "8c1d4f30-2a77-4b91-9de6-5f0a3c2b71e4",
        "name": "The Garcia Family",
        "members": [
          { "role": "mother", "type": "adult", "age": "35-40", "ethnicity": "hispanic", "physical": "medium build, long dark hair", "clothing": "casual blouse" },
          { "role": "father", "type": "adult", "age": "38-45", "ethnicity": "hispanic", "physical": "athletic build, short dark hair", "clothing": "casual polo shirt" },
          { "role": "daughter", "type": "child", "age": "8-10", "ethnicity": "hispanic", "physical": "long dark hair, bright smile" }
        ],
        "card_image_url": "https://media.vibepeak.ai/families/garcia-family-card.jpg",
        "reference_image_urls": [
          "https://media.vibepeak.ai/families/garcia-family-mother.jpg",
          "https://media.vibepeak.ai/families/garcia-family-father.jpg",
          "https://media.vibepeak.ai/families/garcia-family-daughter.jpg"
        ],
        "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "org_id": null,
        "created_at": "2026-06-20T15:30:00Z"
      }
    ]
  }
  ```

  ```json 200 Still Generating theme={null}
  {
    "families": [
      {
        "id": "9c858901-8a57-4791-81fe-4c455b099bc9",
        "scope": "user",
        "slug": "4b98cc4c-2897-49a4-93f9-d721ca4c772b",
        "name": "The Smith Family",
        "members": [
          { "role": "father", "type": "adult" },
          { "role": "mother", "type": "adult" }
        ],
        "card_image_url": null,
        "reference_image_urls": [],
        "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "org_id": null,
        "created_at": "2026-07-09T10:00:00Z"
      }
    ]
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "INVALID_API_KEY",
      "message": "The provided API key is invalid or has been revoked",
      "request_id": "req_xyz123"
    }
  }
  ```
</ResponseExample>

## Usage with Video Creation

Once you've found a family, use its identifier as the `selected_family_id` when creating a living property video so the same cast appears in every scene. Preset families are identified by `slug`; your own families are identified by `id`:

```javascript theme={null}
// 1. List preset families
const familiesResponse = await fetch('https://api.vibepeak.ai/v1/families?type=preset', {
  headers: { 'Authorization': 'Bearer vpk_live_xxxxx' }
});
const { families } = await familiesResponse.json();

// 2. Select a ready family and create a video with it
const selectedFamily = families.find((family) => family.card_image_url !== null);

const videoResponse = await fetch('https://api.vibepeak.ai/v1/real-estate/living-property', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    images: ['https://example.com/property/living-room.jpg', /* ... */],
    voice: { voice_id: 'EXAVITQu4vr4xnSDxMaL', language: 'en' },
    modification_mode: 'no_modify',
    script: 'Welcome to this stunning modern home...',
    selected_family_id: selectedFamily.slug
  })
});
```

## Error Codes

| Code                | Status | Description                                |
| ------------------- | ------ | ------------------------------------------ |
| `INVALID_PARAMETER` | 400    | Invalid value for `type`                   |
| `MISSING_API_KEY`   | 401    | No `Authorization` header was sent         |
| `INVALID_API_KEY`   | 401    | The API key is invalid or has been revoked |

See [Error Handling](/concepts/error-handling) for more details.