List Families

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

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}`);
}

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']}")

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "request_id": "req_xyz123"
  }
}

GET

families

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

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}`);
}

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']}")

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "request_id": "req_xyz123"
  }
}

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

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)

Response

array

required

List of family objects.

Show Family properties

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. Preset families omit id; reference them by slug instead.

string

required

preset for built-in families available to everyone, or user for a family created by an account.

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 or selected_family_id. Address your own families by id.

string | null

required

Display name of the family.

Preset families currently return null here. Their display names (“Family with kids”, “Retired couple”, …) live in the preset gallery, not in the API response. Fall back to the slug when rendering a preset, and treat this field as nullable.

array

required

The members that make up this family’s cast.

Show Member properties

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.

string

Broad age category: adult, child, or senior.Always present on user families. Absent on preset families.

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

string

Free-text age or age range that guided avatar generation, e.g. 35-40.

string

Free-text ethnicity that guided avatar generation.

string

Free-text physical description that guided avatar generation, e.g. athletic build, short dark hair.

string

Free-text clothing description that guided avatar generation, e.g. casual button-down shirt.

string | null

required

Preview image showing the full family together. null while the family’s avatars are still being generated.

string[]

required

Reference image URLs generated for the family’s members.

string | null

required

The account that created the family. null for preset families.

string | null

required

The organization the family is shared with, if any.

string

required

Family creation timestamp (ISO 8601 format).

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

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}`);
}

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']}")

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "request_id": "req_xyz123"
  }
}

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:

// 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 for more details.

Overview

Avatars

Voices

Videos

Families

Images

Query Parameters

Response

Usage with Video Creation

Error Codes

​Query Parameters

​Response

​Usage with Video Creation

​Error Codes

Query Parameters

Response

Usage with Video Creation

Error Codes