# 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"
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}`);
}
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']}")
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"error": {
"code": "FAMILY_NOT_FOUND",
"message": "Family not found or not accessible with this API key.",
"request_id": "req_xyz123"
}
}
Families
Get Family
Retrieve a single family by ID or slug, including its generation status
GET
/
v1
/
families
/
{idOrSlug}
# 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"
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}`);
}
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']}")
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"error": {
"code": "FAMILY_NOT_FOUND",
"message": "Family not found or not accessible with this API key.",
"request_id": "req_xyz123"
}
}
Retrieves a single family. Use this to check whether a family’s avatars have finished generating before using it as
See Error Handling for more details.
selected_family_id in a video.
Path Parameters
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 foruser-scope families.
404 FAMILY_NOT_FOUND if the slug doesn’t match any preset.Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6Response
Returns the same family object as List Families, plus astatus field.
string
Unique identifier for the family. Only present for
user-scope families; preset families omit id.string
required
preset for built-in families available to everyone, or user for a family created by an account.string
required
URL-safe identifier for the family.
string | null
required
Display name of the family.
null for preset families — see
List Families for the details.array
required
The members that make up this family’s cast. See List Families for the member shape — note that preset members carry only
role and have no type.string
required
Generation status of the family.Allowed values:
ready, generating, failed, pending_avatarsPreset families are always ready. A user family created with generate_avatars: false starts as pending_avatars.This field also covers member edits. While
Add,
Update,
Regenerate or
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.string | null
required
Preview image showing the full family together.
null until the family is ready.string[]
required
Reference image URLs generated for the family’s members. Empty until the family is
ready.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).
# 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"
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}`);
}
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']}")
{
"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"
}
{
"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"
}
{
"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"
}
{
"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"
}
{
"error": {
"code": "FAMILY_NOT_FOUND",
"message": "Family not found or not accessible with this API key.",
"request_id": "req_xyz123"
}
}
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 |