---
title: "Update Avatar Group"
method: PATCH
path: "/v3/avatars/{group_id}"
tags: ["Avatars"]
---

# Update Avatar Group

`PATCH /v3/avatars/{group_id}`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/avatars/{group_id}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Updates an avatar group you own. Currently sets `default_voice_id`, the voice this avatar uses by default; any voice in your workspace works, including clones. Public avatars cannot be updated.

## Path parameters

- `group_id` string, required

## Request body

- UpdateAvatarGroupRequest: Request body for PATCH /v3/avatars/{group_id}.
  - `default_voice_id` string, nullable: Voice ID to set as the avatar's default voice, replacing the current one. The voice is also linked to the avatar group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own.

## Response `200`

Successful response

- object
  - `data` AvatarGroupItem: A single avatar group in the list response. Groups are containers for looks (outfits/styles). To determine avatar type and engine compatibility, fetch the looks via GET /v3/avatars/looks.
    - `id` string, required: Unique avatar group identifier.
    - `name` string, required: Display name of the avatar.
    - `preview_image_url` string, nullable: URL to the avatar preview image.
    - `preview_video_url` string, nullable: URL to the avatar preview video.
    - `gender` string, nullable: Gender of the avatar.
    - `created_at` integer, required: Unix timestamp (seconds) when the avatar was created.
    - `looks_count` integer, required: Number of looks (outfits/styles) available for this avatar.
    - `default_voice_id` string, nullable: Default voice ID for this avatar.
    - `consent_status` string, nullable: The consent status for the group. When null or omitted, no status is recorded; consent may still be required before video generation.
    - `status` 'processing' | 'pending_consent' | 'failed' | 'completed': Training/creation status of an avatar group or look.
    - `error` AvatarError: Error details for a failed avatar creation.
      - `code` string, required: Machine-readable error code.
      - `message` string, required: Human-readable error description.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `403`: Forbidden — `error.code` is one of: `resource_access_denied`, `forbidden`, `voice_not_usable`.
- `404`: Resource not found
- `409`: Conflict
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/avatars/:group_id/patch.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)