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

# Get Family

> Retrieve a single family by ID or slug, including its generation status

Retrieves a single family. Use this to check whether a family's avatars have finished generating before using it as `selected_family_id` in a video.

## Path Parameters

<ParamField path="idOrSlug" type="string" required>
  The identifier of the family.

  * For any family visible to you (a preset, one of yours, or one shared by your organization), pass its **UUID**.
  * For **preset** families only, you may pass the **slug** instead, e.g. `family-with-kids`. Slugs are not accepted for `user`-scope families.

  Returns `404 FAMILY_NOT_FOUND` if the slug doesn't match any preset.

  Example: `3fa85f64-5717-4562-b3fc-2c963f66afa6`
</ParamField>

## Response

Returns the same family object as [List Families](/api-reference/families/list-families), plus a `status` field.

<ResponseField name="id" type="string">
  Unique identifier for the family. Only present for `user`-scope families; preset families omit `id`.
</ResponseField>

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

<ResponseField name="slug" type="string" required>
  URL-safe identifier for the family.
</ResponseField>

<ResponseField name="name" type="string | null" required>
  Display name of the family. **`null` for preset families** — see
  [List Families](/api-reference/families/list-families) for the details.
</ResponseField>

<ResponseField name="members" type="array" required>
  The members that make up this family's cast. See [List Families](/api-reference/families/list-families) for the member shape — note that preset members carry only `role` and have no `type`.
</ResponseField>

<ResponseField name="status" type="string" required>
  Generation status of the family.

  **Allowed values:** `ready`, `generating`, `failed`, `pending_avatars`

  Preset families are always `ready`. A `user` family created with `generate_avatars: false` starts as `pending_avatars`.

  <Note>
    This field also covers member edits. While
    [Add](/api-reference/families/add-family-member),
    [Update](/api-reference/families/update-family-member),
    [Regenerate](/api-reference/families/regenerate-family-member) or
    [Remove Family Member](/api-reference/families/remove-family-member) is
    running, the family reports `generating` and write requests are rejected
    with `422 FAMILY_NOT_READY` — the two agree, so polling this endpoint until
    `ready` is a valid way to wait for an edit. Polling the `task_id` the edit
    returned is still the more direct option, and the only one that surfaces a
    failure reason.
  </Note>
</ResponseField>

<ResponseField name="card_image_url" type="string | null" required>
  Preview image showing the full family together. `null` until the family is `ready`.
</ResponseField>

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

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

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

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

<RequestExample>
  ```bash cURL theme={null}
  # By UUID (any family visible to you)
  curl https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
    -H "Authorization: Bearer vpk_live_xxxxx"

  # By slug (presets only)
  curl https://api.vibepeak.ai/v1/families/young-family \
    -H "Authorization: Bearer vpk_live_xxxxx"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6', {
    headers: {
      'Authorization': 'Bearer vpk_live_xxxxx'
    }
  });

  const family = await response.json();
  console.log(`Status: ${family.status}`);

  if (family.status === 'ready') {
    console.log(`Card image: ${family.card_image_url}`);
  }
  ```

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

  response = requests.get(
      'https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6',
      headers={
          'Authorization': 'Bearer vpk_live_xxxxx'
      }
  )

  family = response.json()
  print(f"Status: {family['status']}")

  if family['status'] == 'ready':
      print(f"Card image: {family['card_image_url']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Ready (by UUID) theme={null}
  {
    "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" }
    ],
    "status": "ready",
    "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 Ready (by slug, preset) theme={null}
  {
    "scope": "preset",
    "slug": "family-with-kids",
    "name": null,
    "members": [
      { "role": "adult" },
      { "role": "adult" },
      { "role": "child" },
      { "role": "child" }
    ],
    "status": "ready",
    "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"
  }
  ```

  ```json 200 Generating theme={null}
  {
    "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" }
    ],
    "status": "generating",
    "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 200 Failed theme={null}
  {
    "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" }
    ],
    "status": "failed",
    "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 404 Not Found theme={null}
  {
    "error": {
      "code": "FAMILY_NOT_FOUND",
      "message": "Family not found or not accessible with this API key.",
      "request_id": "req_xyz123"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code               | Status | Description                                                                                                                |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `FAMILY_NOT_FOUND` | 404    | Family doesn't exist, the slug doesn't match a preset, or the family isn't a preset, yours, or shared by your organization |
| `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.