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

# Add Family Member

> Add a new member to a family and regenerate its cast

Adds a new member to a family you own, then regenerates the member's portrait and the family's group `card_image_url`. Only the family's owner can add members.

<Info>
  Adding a family member requires a **Pro**, **Max**, or **Enterprise** plan, like all other family write operations.
</Info>

The family must be in `ready` status: if another generation is already in progress for this family, the request is rejected with `422 FAMILY_NOT_READY`. A family can have at most **6** members; adding a 7th is rejected with `422 FAMILY_MEMBER_LIMIT_EXCEEDED`.

## Path Parameters

<ParamField path="familyId" type="string" required>
  The UUID of the family to add a member to. Only accepts families you own.

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

## Request Body

<ParamField body="type" type="string" required>
  Broad age category.

  **Allowed values:** `adult`, `child`, `senior`

  Guides how the member is depicted in generated scenes.
</ParamField>

<ParamField body="role" type="string">
  Short descriptive label for this member's role in the family, e.g. `father`, `mother`, `daughter`, `grandmother`. This guides avatar generation and how the member is referred to internally.
</ParamField>

<ParamField body="age" type="string">
  Free-text age or age range to guide avatar generation, e.g. `5-7`.
</ParamField>

<ParamField body="ethnicity" type="string">
  Free-text ethnicity to guide avatar generation.
</ParamField>

<ParamField body="physical" type="string">
  Free-text physical description to guide avatar generation, e.g. `short dark hair, bright smile`.
</ParamField>

<ParamField body="clothing" type="string">
  Free-text clothing description to guide avatar generation, e.g. `casual t-shirt and shorts`.
</ParamField>

<ParamField body="webhook_url" type="string">
  HTTPS URL to receive a webhook notification when the new portrait finishes generating.

  See [Webhooks](/concepts/webhooks) for payload format and verification details.

  <Warning>
    Webhook URLs must use HTTPS and cannot point to private/internal networks (SSRF protection).
  </Warning>
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Optional idempotency key. Retrying a request with the same key returns the original result instead of adding a duplicate member.
</ParamField>

## Response

Returns a `202 Accepted` response with a task to poll:

<ResponseField name="family_id" type="string" required>
  Unique identifier for the family.
</ResponseField>

<ResponseField name="task_id" type="string" required>
  Unique identifier for the generation task. Poll it via [Get Task](/api-reference/videos/get-task), or use `webhook_url` for a notification instead.
</ResponseField>

<ResponseField name="status" type="string" required>
  Always `generating` for this response shape.
</ResponseField>

<ResponseField name="livemode" type="boolean" required>
  `true` for live (`vpk_live_`) requests; `false` for test-mode (`vpk_test_`) requests. See [Test Mode](/concepts/test-mode).
</ResponseField>

<ResponseField name="_links" type="object" required>
  HATEOAS links for navigation.

  * `self`: URL to fetch the family (`/v1/families/{family_id}`)
  * `task`: URL to poll for the generation task (`/v1/tasks/{task_id}`)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members \
    -H "Authorization: Bearer vpk_live_xxxxx" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: 7d9f3e2b-4c5d-4e6f-a0b1-2c3d4e5f6a7b" \
    -d '{
      "role": "son",
      "type": "child",
      "age": "5-7",
      "ethnicity": "hispanic",
      "physical": "short dark hair, bright smile",
      "clothing": "casual t-shirt and shorts"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer vpk_live_xxxxx',
      'Content-Type': 'application/json',
      'Idempotency-Key': crypto.randomUUID()
    },
    body: JSON.stringify({
      role: 'son',
      type: 'child',
      age: '5-7',
      ethnicity: 'hispanic',
      physical: 'short dark hair, bright smile',
      clothing: 'casual t-shirt and shorts'
    })
  });

  const result = await response.json();
  console.log(`Adding member, task: ${result.task_id}`);
  ```

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

  response = requests.post(
      'https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members',
      headers={
          'Authorization': 'Bearer vpk_live_xxxxx',
          'Content-Type': 'application/json',
          'Idempotency-Key': str(uuid.uuid4())
      },
      json={
          'role': 'son',
          'type': 'child',
          'age': '5-7',
          'ethnicity': 'hispanic',
          'physical': 'short dark hair, bright smile',
          'clothing': 'casual t-shirt and shorts'
      }
  )

  result = response.json()
  print(f"Adding member, task: {result['task_id']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 202 Accepted theme={null}
  {
    "family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "task_id": "task_fam456add",
    "status": "generating",
    "livemode": true,
    "_links": {
      "self": "/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "task": "/v1/tasks/task_fam456add"
    }
  }
  ```

  ```json 403 Forbidden (Plan Not Allowed) theme={null}
  {
    "error": {
      "code": "PLAN_NOT_ALLOWED",
      "message": "Families are available on the Pro, Max and Enterprise plans. Upgrade your plan to use this feature.",
      "request_id": "req_xyz123"
    }
  }
  ```

  ```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"
    }
  }
  ```

  ```json 422 Unprocessable Entity (Family Not Ready) theme={null}
  {
    "error": {
      "code": "FAMILY_NOT_READY",
      "message": "Another generation is already in progress for this family. Poll the task until it finishes, then retry.",
      "request_id": "req_xyz123"
    }
  }
  ```

  ```json 422 Unprocessable Entity (Member Limit Exceeded) theme={null}
  {
    "error": {
      "code": "FAMILY_MEMBER_LIMIT_EXCEEDED",
      "message": "A family must have between 1 and 6 members.",
      "request_id": "req_xyz123"
    }
  }
  ```
</ResponseExample>

## Polling for Completion

Poll the returned `task_id` via [Get Task](/api-reference/videos/get-task). Once `status` is `completed`, [Get Family](/api-reference/families/get-family) reflects the new member, its portrait, and the regenerated group `card_image_url`.

If the task fails, the family is left **exactly as it was**: the new member is not added and no existing assets are changed.

## Error Codes

| Code                           | Status | Description                                                                 |
| ------------------------------ | ------ | --------------------------------------------------------------------------- |
| `VALIDATION_ERROR`             | 400    | Invalid request parameters                                                  |
| `MISSING_API_KEY`              | 401    | No `Authorization` header was sent                                          |
| `INVALID_API_KEY`              | 401    | The API key is invalid or has been revoked                                  |
| `PLAN_NOT_ALLOWED`             | 403    | Your plan doesn't allow editing a family (requires Pro, Max, or Enterprise) |
| `FAMILY_NOT_FOUND`             | 404    | Family doesn't exist or isn't yours                                         |
| `FAMILY_NOT_READY`             | 422    | Another generation is already in progress for this family                   |
| `FAMILY_MEMBER_LIMIT_EXCEEDED` | 422    | The family already has the maximum of 6 members                             |

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