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. The result is replayed for 24 hours, except 402 and 429 responses, which are never stored: retrying after backing off or topping up credits is processed normally.

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.