Skip to main content
PATCH
Updates one or more descriptors of an existing family member you own, then regenerates that member’s portrait and the family’s group 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.
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.

Path Parameters

string
required
The UUID of the family. Only accepts families you own.Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
integer
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: 2

Request 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, senior
string
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 a 202 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.
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})

Polling for Completion

Poll the returned task_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

See Error Handling for more details.