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
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"
⌘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"
}
}
}
