Avatars

Create Avatar Looks

Generates new looks for an existing avatar. reference_look_id is an existing look used as the identity reference; the new looks are added to its avatar. type selects the method. look_pack applies a Look Pack: template_id is a public Look Pack template, or an enterprise custom pack assigned to your workspace, and the pack decides how many looks are generated; generation is always 16:9, and aspect_ratio: "9:16" center-crops the delivered frames to portrait. template restyles the look into a single look template, producing two looks in the template’s aspect ratio. Billing happens when the request is accepted: an API key is charged 1 API credit per look generated; a connected integration is charged the method’s standard price from the workspace’s credits. Free-tier MCP access cannot use this endpoint. The response lists the new looks’ ids; poll GET /v3/avatars/looks/{id} until each is completed or failed.

POST

avatars

looks

Create Avatar Looks

curl --request POST \
  --url https://api.heygen.com/v3/avatars/looks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "look_pack",
  "reference_look_id": "<string>",
  "template_id": "<string>"
}
'

import requests

url = "https://api.heygen.com/v3/avatars/looks"

payload = {
    "type": "look_pack",
    "reference_look_id": "<string>",
    "template_id": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: 'look_pack', reference_look_id: '<string>', template_id: '<string>'})
};

fetch('https://api.heygen.com/v3/avatars/looks', 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/looks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'look_pack',
    'reference_look_id' => '<string>',
    'template_id' => '<string>'
  ]),
  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/looks"

	payload := strings.NewReader("{\n  \"type\": \"look_pack\",\n  \"reference_look_id\": \"<string>\",\n  \"template_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.heygen.com/v3/avatars/looks")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"look_pack\",\n  \"reference_look_id\": \"<string>\",\n  \"template_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/avatars/looks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"look_pack\",\n  \"reference_look_id\": \"<string>\",\n  \"template_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "group_id": "<string>",
    "looks": [
      {
        "id": "<string>"
      }
    ]
  }
}

Authorizations

x-api-key

string

header

required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key

string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

CreateLookPackLooksRequest
CreateTemplateLooksRequest

Generate a Look Pack's looks into the avatar an existing look belongs to.

type

string

required

Generation method. 'look_pack' applies a Look Pack template.

Allowed value: "look_pack"

reference_look_id

string

required

An existing avatar look used as the identity reference. The new looks are added to its avatar.

Required string length: 1 - 128

template_id

string

required

The Look Pack template to apply: a public template, or an enterprise custom pack assigned to your workspace.

Required string length: 1 - 128

aspect_ratio

enum<string> | null

Output aspect ratio, '16:9' by default. Generation is always 16:9; '9:16' center-crops the delivered frames to portrait as the final step.

Available options:

16:9,

9:16

Response

Successful response

data

CreateAvatarLooksResponse · object

Response for POST /v3/avatars/looks.

Show child attributes

⌘I

Create Avatar Looks

curl --request POST \
  --url https://api.heygen.com/v3/avatars/looks \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "type": "look_pack",
  "reference_look_id": "<string>",
  "template_id": "<string>"
}
'

import requests

url = "https://api.heygen.com/v3/avatars/looks"

payload = {
    "type": "look_pack",
    "reference_look_id": "<string>",
    "template_id": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({type: 'look_pack', reference_look_id: '<string>', template_id: '<string>'})
};

fetch('https://api.heygen.com/v3/avatars/looks', 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/looks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'look_pack',
    'reference_look_id' => '<string>',
    'template_id' => '<string>'
  ]),
  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/looks"

	payload := strings.NewReader("{\n  \"type\": \"look_pack\",\n  \"reference_look_id\": \"<string>\",\n  \"template_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.heygen.com/v3/avatars/looks")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"look_pack\",\n  \"reference_look_id\": \"<string>\",\n  \"template_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.heygen.com/v3/avatars/looks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"look_pack\",\n  \"reference_look_id\": \"<string>\",\n  \"template_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "group_id": "<string>",
    "looks": [
      {
        "id": "<string>"
      }
    ]
  }
}

Video Agent

Brand

Avatars

Audio

Voices

Videos

Templates

Video Translate

Lipsync

HyperFrames

User

API Keys

Webhooks

Assets

AI Clipping

Filler Word Removal

Batches

Video Translation Batches

Lipsync Batches

Asset Batches

Create Avatar Looks

Authorizations

Headers

Body

Response