curl -X PATCH https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2 \
-H "Authorization: Bearer vpk_live_xxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8e0a4f3c-5d6e-4f7a-b1c2-3d4e5f6a7b8c" \
-d '{
"clothing": "school uniform"
}'
const response = await fetch('https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer vpk_live_xxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
clothing: 'school uniform'
})
});
const result = await response.json();
console.log(`Updating member, task: ${result.task_id}`);
import requests
import uuid
response = requests.patch(
'https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2',
headers={
'Authorization': 'Bearer vpk_live_xxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': str(uuid.uuid4())
},
json={
'clothing': 'school uniform'
}
)
result = response.json()
print(f"Updating member, task: {result['task_id']}")
{
"family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"task_id": "task_fam457upd",
"status": "generating",
"livemode": true,
"_links": {
"self": "/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"task": "/v1/tasks/task_fam457upd"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "At least one member field must be provided",
"details": {
"field": "unknown",
"issues": [{ "path": "", "message": "At least one member field must be provided" }]
},
"request_id": "req_xyz123"
}
}
{
"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_NOT_FOUND",
"message": "Family not found or not accessible with this API key.",
"request_id": "req_xyz123"
}
}
{
"error": {
"code": "FAMILY_MEMBER_NOT_FOUND",
"message": "Member index is out of range for this family.",
"request_id": "req_xyz123"
}
}
{
"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"
}
}
Families
Update Family Member
Update a family member’s descriptors and regenerate their portrait
PATCH
/
v1
/
families
/
{familyId}
/
members
/
{index}
curl -X PATCH https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2 \
-H "Authorization: Bearer vpk_live_xxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8e0a4f3c-5d6e-4f7a-b1c2-3d4e5f6a7b8c" \
-d '{
"clothing": "school uniform"
}'
const response = await fetch('https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer vpk_live_xxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
clothing: 'school uniform'
})
});
const result = await response.json();
console.log(`Updating member, task: ${result.task_id}`);
import requests
import uuid
response = requests.patch(
'https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2',
headers={
'Authorization': 'Bearer vpk_live_xxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': str(uuid.uuid4())
},
json={
'clothing': 'school uniform'
}
)
result = response.json()
print(f"Updating member, task: {result['task_id']}")
{
"family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"task_id": "task_fam457upd",
"status": "generating",
"livemode": true,
"_links": {
"self": "/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"task": "/v1/tasks/task_fam457upd"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "At least one member field must be provided",
"details": {
"field": "unknown",
"issues": [{ "path": "", "message": "At least one member field must be provided" }]
},
"request_id": "req_xyz123"
}
}
{
"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_NOT_FOUND",
"message": "Family not found or not accessible with this API key.",
"request_id": "req_xyz123"
}
}
{
"error": {
"code": "FAMILY_MEMBER_NOT_FOUND",
"message": "Member index is out of range for this family.",
"request_id": "req_xyz123"
}
}
{
"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"
}
}
Updates one or more descriptors of an existing family member you own, then regenerates that member’s portrait and the family’s group
The family must be in
See Error Handling for more details.
card_image_url to reflect the change. Only the family’s owner can update members.
Updating a family member requires a Pro, Max, or Enterprise plan, like all other family write operations.
ready status: if another generation is already in progress for this family, the request is rejected with 422 FAMILY_NOT_READY.
Path Parameters
string
required
The UUID of the family. Only accepts families you own.Example:
3fa85f64-5717-4562-b3fc-2c963f66afa6integer
required
The 0-based position of the member to update, matching the order of the
members array returned by Get Family.Returns 404 FAMILY_MEMBER_NOT_FOUND if out of range.Example: 2Request Body
At least one field is required. Only the fields you include are changed; the rest keep their current value.string
Broad age category.Allowed values:
adult, child, seniorstring
Short descriptive label for this member’s role in the family, e.g.
father, mother, daughter, grandmother.string
Free-text age or age range to guide avatar generation, e.g.
8-10.string
Free-text ethnicity to guide avatar generation.
string
Free-text physical description to guide avatar generation, e.g.
long dark hair, bright smile.string
Free-text clothing description to guide avatar generation, e.g.
school uniform.string
HTTPS URL to receive a webhook notification when the updated portrait finishes generating.See Webhooks for payload format and verification details.
Webhook URLs must use HTTPS and cannot point to private/internal networks (SSRF protection).
string
Optional idempotency key. Retrying a request with the same key returns the original result instead of applying the update twice.
Response
Returns a202 Accepted response with a task to poll:
string
required
Unique identifier for the family.
string
required
Unique identifier for the generation task. Poll it via Get Task, or use
webhook_url for a notification instead.string
required
Always
generating for this response shape.boolean
required
true for live (vpk_live_) requests; false for test-mode (vpk_test_) requests. See Test Mode.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})
curl -X PATCH https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2 \
-H "Authorization: Bearer vpk_live_xxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8e0a4f3c-5d6e-4f7a-b1c2-3d4e5f6a7b8c" \
-d '{
"clothing": "school uniform"
}'
const response = await fetch('https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2', {
method: 'PATCH',
headers: {
'Authorization': 'Bearer vpk_live_xxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID()
},
body: JSON.stringify({
clothing: 'school uniform'
})
});
const result = await response.json();
console.log(`Updating member, task: ${result.task_id}`);
import requests
import uuid
response = requests.patch(
'https://api.vibepeak.ai/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6/members/2',
headers={
'Authorization': 'Bearer vpk_live_xxxxx',
'Content-Type': 'application/json',
'Idempotency-Key': str(uuid.uuid4())
},
json={
'clothing': 'school uniform'
}
)
result = response.json()
print(f"Updating member, task: {result['task_id']}")
{
"family_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"task_id": "task_fam457upd",
"status": "generating",
"livemode": true,
"_links": {
"self": "/v1/families/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"task": "/v1/tasks/task_fam457upd"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "At least one member field must be provided",
"details": {
"field": "unknown",
"issues": [{ "path": "", "message": "At least one member field must be provided" }]
},
"request_id": "req_xyz123"
}
}
{
"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_NOT_FOUND",
"message": "Family not found or not accessible with this API key.",
"request_id": "req_xyz123"
}
}
{
"error": {
"code": "FAMILY_MEMBER_NOT_FOUND",
"message": "Member index is out of range for this family.",
"request_id": "req_xyz123"
}
}
{
"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"
}
}
Polling for Completion
Poll the returnedtask_id via Get Task. Once status is completed, Get Family reflects the updated member and the regenerated group card_image_url.
If the task fails, the family is left exactly as it was: the member’s descriptors and portrait remain unchanged.
Error Codes
| Code | Status | Description |
|---|---|---|
VALIDATION_ERROR | 400 | Invalid request parameters, or no fields provided |
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_MEMBER_NOT_FOUND | 404 | index is out of range for this family’s members array |
FAMILY_NOT_READY | 422 | Another generation is already in progress for this family |

