Avatars
Update Avatar Group
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.
PATCH
/
v3
/
avatars
/
{group_id}
Update Avatar Group
curl --request PATCH \
--url https://api.heygen.com/v3/avatars/{group_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2"
}
'import requests
url = "https://api.heygen.com/v3/avatars/{group_id}"
payload = { "default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2" }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({default_voice_id: '1bd001e7e50f421d891986aad5c8bbd2'})
};
fetch('https://api.heygen.com/v3/avatars/{group_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.heygen.com/v3/avatars/{group_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'default_voice_id' => '1bd001e7e50f421d891986aad5c8bbd2'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.heygen.com/v3/avatars/{group_id}"
payload := strings.NewReader("{\n \"default_voice_id\": \"1bd001e7e50f421d891986aad5c8bbd2\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.heygen.com/v3/avatars/{group_id}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"default_voice_id\": \"1bd001e7e50f421d891986aad5c8bbd2\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heygen.com/v3/avatars/{group_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"default_voice_id\": \"1bd001e7e50f421d891986aad5c8bbd2\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "ag_abc123",
"name": "Anna",
"created_at": 1711929600,
"looks_count": 3,
"preview_image_url": "https://files.heygen.ai/avatar/anna_preview.jpg",
"preview_video_url": "https://files.heygen.ai/avatar/anna_preview.mp4",
"gender": "female",
"default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
"consent_status": "accepted",
"status": "completed",
"error": {
"code": "training_failed",
"message": "Footage duration must be between 15s and 600s"
}
}
}Authorizations
ApiKeyAuthBearerAuth
HeyGen API key. Obtain from your HeyGen dashboard.
Path Parameters
Unique avatar group identifier
Body
application/json
Request body for PATCH /v3/avatars/{group_id}.
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.
Maximum string length:
255Example:
"1bd001e7e50f421d891986aad5c8bbd2"
Response
Successful response
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.
Show child attributes
Show child attributes
⌘I
Update Avatar Group
curl --request PATCH \
--url https://api.heygen.com/v3/avatars/{group_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2"
}
'import requests
url = "https://api.heygen.com/v3/avatars/{group_id}"
payload = { "default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2" }
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({default_voice_id: '1bd001e7e50f421d891986aad5c8bbd2'})
};
fetch('https://api.heygen.com/v3/avatars/{group_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.heygen.com/v3/avatars/{group_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'default_voice_id' => '1bd001e7e50f421d891986aad5c8bbd2'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.heygen.com/v3/avatars/{group_id}"
payload := strings.NewReader("{\n \"default_voice_id\": \"1bd001e7e50f421d891986aad5c8bbd2\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.heygen.com/v3/avatars/{group_id}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"default_voice_id\": \"1bd001e7e50f421d891986aad5c8bbd2\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.heygen.com/v3/avatars/{group_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"default_voice_id\": \"1bd001e7e50f421d891986aad5c8bbd2\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "ag_abc123",
"name": "Anna",
"created_at": 1711929600,
"looks_count": 3,
"preview_image_url": "https://files.heygen.ai/avatar/anna_preview.jpg",
"preview_video_url": "https://files.heygen.ai/avatar/anna_preview.mp4",
"gender": "female",
"default_voice_id": "1bd001e7e50f421d891986aad5c8bbd2",
"consent_status": "accepted",
"status": "completed",
"error": {
"code": "training_failed",
"message": "Footage duration must be between 15s and 600s"
}
}
}