curl -X POST https://api.vibepeak.ai/v1/families \
  -H "Authorization: Bearer vpk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c8f2e1a-3b4d-4e5f-9a0b-1c2d3e4f5a6b" \
  -d '{
    "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" }
    ],
    "webhook_url": "https://yourserver.com/webhooks/vibepeak"
  }'

const response = await fetch('https://api.vibepeak.ai/v1/families', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vpk_live_xxxxx',
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    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' }
    ],
    webhook_url: 'https://yourserver.com/webhooks/vibepeak'
  })
});

const family = await response.json();
console.log(`Family created: ${family.family_id} (task: ${family.task_id})`);

import requests
import uuid

response = requests.post(
    'https://api.vibepeak.ai/v1/families',
    headers={
        'Authorization': 'Bearer vpk_live_xxxxx',
        'Content-Type': 'application/json',
        'Idempotency-Key': str(uuid.uuid4())
    },
    json={
        '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'}
        ],
        'webhook_url': 'https://yourserver.com/webhooks/vibepeak'
    }
)

family = response.json()
print(f"Family created: {family['family_id']} (task: {family['task_id']})")

{
  "family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "task_id": "task_fam456xyz",
  "status": "generating",
  "livemode": true,
  "_links": {
    "self": "/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "task": "/v1/tasks/task_fam456xyz"
  }
}

{
  "family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "task_id": "task_fam456xyz",
  "status": "generating",
  "livemode": false,
  "_links": {
    "self": "/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "task": "/v1/tasks/task_fam456xyz"
  }
}

{
  "family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "pending_avatars"
}

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

{
  "error": {
    "code": "FAMILY_MEMBER_LIMIT_EXCEEDED",
    "message": "A family must have between 1 and 6 members.",
    "request_id": "req_xyz123"
  }
}

{
  "error": {
    "code": "FAMILY_LIMIT_REACHED",
    "message": "You have reached the maximum number of families for your plan. Delete an existing family to create a new one.",
    "request_id": "req_xyz123"
  }
}

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