> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update Avatar Group > Updates an avatar group. Currently supports setting `default_voice_id`: the voice becomes the avatar's default for video generation and is linked to the group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own — public avatars cannot be updated. ## OpenAPI ````yaml /openapi/external-api.json patch /v3/avatars/{group_id} openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Filler Word Removal description: '' paths: /v3/avatars/{group_id}: patch: tags: - Avatars summary: Update Avatar Group description: >- Updates an avatar group. Currently supports setting `default_voice_id`: the voice becomes the avatar's default for video generation and is linked to the group if it was not already. Accepts any voice available to your workspace, including imported voice clones. Only supported for avatars you own — public avatars cannot be updated. operationId: updateAvatarGroup parameters: - name: group_id in: path required: true schema: type: string description: Unique avatar group identifier requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAvatarGroupRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AvatarGroupItem' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: invalid_parameter message: 'Invalid default_voice_id: ''abc123''. Voice not found.' param: null doc_url: >- https://developers.heygen.com/docs/error-codes#invalid-parameter '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '403': description: >- Forbidden — `error.code` is one of: `resource_access_denied`, `forbidden`, `voice_not_usable`. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: resource_access_denied: summary: Caller lacks write access to this avatar group value: error: code: resource_access_denied message: Forbidden param: null doc_url: >- https://developers.heygen.com/docs/error-codes#resource-access-denied forbidden: summary: >- Workspace policy restricts avatar editing to the owner or an admin value: error: code: forbidden message: >- Only the avatar owner or a workspace admin can edit this avatar. param: null doc_url: https://developers.heygen.com/docs/error-codes#forbidden voice_not_usable: summary: The voice exists but is not usable by this workspace value: error: code: voice_not_usable message: >- This voice can't be used to generate this video. Please select a different voice to continue. param: null doc_url: >- https://developers.heygen.com/docs/error-codes#voice-not-usable '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: avatar_not_found message: Avatar group ag_abc123 not found. param: null doc_url: >- https://developers.heygen.com/docs/error-codes#avatar-not-found '409': description: Conflict content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: resource_not_ready message: >- This voice is still being created. Please try again in a moment. param: null doc_url: >- https://developers.heygen.com/docs/error-codes#resource-not-ready '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: UpdateAvatarGroupRequest: additionalProperties: false description: Request body for PATCH /v3/avatars/{group_id}. properties: default_voice_id: anyOf: - maxLength: 255 type: string - type: 'null' default: null description: >- 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. examples: - 1bd001e7e50f421d891986aad5c8bbd2 title: Default Voice Id title: UpdateAvatarGroupRequest type: object AvatarGroupItem: description: >- 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. properties: id: description: Unique avatar group identifier. examples: - ag_abc123 title: Id type: string name: description: Display name of the avatar. examples: - Anna title: Name type: string preview_image_url: anyOf: - type: string - type: 'null' default: null description: URL to the avatar preview image. examples: - https://files.heygen.ai/avatar/anna_preview.jpg title: Preview Image Url preview_video_url: anyOf: - type: string - type: 'null' default: null description: URL to the avatar preview video. examples: - https://files.heygen.ai/avatar/anna_preview.mp4 title: Preview Video Url gender: anyOf: - type: string - type: 'null' default: null description: Gender of the avatar. examples: - female title: Gender created_at: description: Unix timestamp (seconds) when the avatar was created. examples: - 1711929600 title: Created At type: integer looks_count: description: Number of looks (outfits/styles) available for this avatar. examples: - 3 title: Looks Count type: integer default_voice_id: anyOf: - type: string - type: 'null' default: null description: Default voice ID for this avatar. examples: - 1bd001e7e50f421d891986aad5c8bbd2 title: Default Voice Id consent_status: anyOf: - type: string - type: 'null' default: null description: >- The status of consent for the group. None means consent is not required. examples: - approved title: Consent Status status: anyOf: - $ref: '#/components/schemas/AvatarStatus' - type: 'null' default: null description: >- Training status of the avatar group. Only present for private avatars. examples: - completed error: anyOf: - $ref: '#/components/schemas/AvatarError' - type: 'null' default: null description: Error details. Only present when status is 'failed'. required: - id - name - created_at - looks_count title: AvatarGroupItem type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' required: - code - message AvatarStatus: description: Training/creation status of an avatar group or look. enum: - processing - pending_consent - failed - completed title: AvatarStatus type: string AvatarError: description: Error details for a failed avatar creation. properties: code: description: Machine-readable error code. examples: - training_failed title: Code type: string message: description: Human-readable error description. examples: - Footage duration must be between 15s and 600s title: Message type: string required: - code - message title: AvatarError type: object StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````