Look Packs and Templates

Generate a coordinated set of looks for an avatar you already own with POST /v3/avatars/looks. Apply a Look Pack for a full set, or a single look template to restyle one look.

POST /v3/avatars/looks dresses an avatar you already own in curated looks. Give it one existing look as the identity reference and a curated template_id, and the new looks join that look’s character.

Where prompting gives you one look at a time in your own words, a pack gives you a whole coordinated set in one call.

1. Pick a method

   type	What it applies	How many looks
   look_pack	A Look Pack: a curated set built around one theme.	The pack decides. Every pack in the gallery today produces five.
   template	A single look template, restyling the reference look into it.	Two, in the template’s aspect ratio.

2. Pick a template id

   Eight packs from the gallery. Style packs, the first four, keep the setting neutral and move the wardrobe and palette. Role packs, the last four, put your avatar into a job with the wardrobe and setting that go with it.

   

   Modern Corporate

   

   Stylish Business-Casual

   

   Scandinavian Minimal

   

   Cool Tech / Slate

   

   Healthcare

   

   Keynote Power Presenter

   

   Fitness

   

   Automotive Dealership

   Template ids are 32-character hex strings, and every pack ships as a female and a male variant, so pick the one matching your avatar.

   Look Pack	Female	Male
   Modern Corporate	5a8e6be843ee4321a014946bf62aa322	5e659e76755d47fd9160a2d7dedce124
   Stylish Business-Casual	e1650a9029d04ea1a350421c163295fd	a5f8e0c0cb654c1a83c695629b173af5
   Scandinavian Minimal	e7b000e2cb0d44f1a2d2f291a38b395a	9600f78f27bb49d792e1c56ce624b929
   Cool Tech / Slate	d7ad40ec97d4459a92b33398b57caf4e	fbd03fc3603a4e3caff594f5743a1733
   Healthcare	14f4070bd5a04eb6b1f82ae087cd0f30	ce706bfa8556401e8c4401765102a455
   Keynote Power Presenter	b0cae4fbae384ab9ab9a8e73ba504be8	71e84769162d4f4186563ad9e0fc45b8
   Fitness	935ea0b7cdde4e6eb5a198a3d666f677	daeb8b15c92a4acf9ffb437ba5534458
   Automotive Dealership	6f183d726933457c9035fc0aa4e9c0c3	8595c78b466c4e51802731229c59b6e7

   The full gallery is browsable in the HeyGen app, covering real estate, legal, teaching, construction and more. Enterprise workspaces can have custom packs built and assigned to them, which then work here exactly like the rest. To have one assigned, contact sales.

3. Send the request

   Look Pack

   # Reuse this key when retrying this exact request in the same shell.
   # For a different Look Pack request, unset LOOK_PACK_KEY first.
   LOOK_PACK_KEY="${LOOK_PACK_KEY:-$(uuidgen)}"
   
   curl -X POST "https://api.heygen.com/v3/avatars/looks" \
     -H "X-Api-Key: $HEYGEN_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $LOOK_PACK_KEY" \
     -d '{
       "type": "look_pack",
       "reference_look_id": "look_abc123",
       "template_id": "5a8e6be843ee4321a014946bf62aa322",
       "aspect_ratio": "16:9"
     }'
   

   Packs generate at 16:9. Pass aspect_ratio: "9:16" and the delivered frames are center-cropped to portrait as the final step, which is worth knowing when you plan the framing of the reference look.

   Single template

   # Reuse this key when retrying this exact request in the same shell.
   # For a different single-template request, unset SINGLE_TEMPLATE_KEY first.
   SINGLE_TEMPLATE_KEY="${SINGLE_TEMPLATE_KEY:-$(uuidgen)}"
   
   curl -X POST "https://api.heygen.com/v3/avatars/looks" \
     -H "X-Api-Key: $HEYGEN_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $SINGLE_TEMPLATE_KEY" \
     -d '{
       "type": "template",
       "reference_look_id": "look_abc123",
       "template_id": "b30c83d99cec48e09c8f5b07ed8aa38c"
     }'
   

   A single template returns two looks in the template’s own aspect ratio, so aspect_ratio does not apply here.

   Single templates are one card each rather than a themed set. The id above is Business Casual for a female avatar. The male one is 2dc326030e2e4471babcc9eda56131b6, and Podcast is 00c49daa4eb94386a0c12508043bab17 for female and 0e52ceafe4d5456fb83c1e39899ff76a for male.

   reference_look_id is any look you own, from a digital twin, a photo, or a prompt. Its character is where the results land, so there is no group field to set.

4. Poll the new looks

   The response names the character the looks joined and gives one id per look being generated:

   {
     "data": {
       "group_id": "group_xyz789",
       "looks": [
         { "id": "look_def456" },
         { "id": "look_ghi789" },
         { "id": "look_jkl012" },
         { "id": "look_mno345" },
         { "id": "look_pqr678" }
       ]
     }
   }
   

   Each id starts at processing. Poll GET /v3/avatars/looks/{look_id} until it reports completed, at which point the preview is available and the id is usable as avatar_id for POST /v3/videos, or failed, where error.message gives the reason.

   To see every look on the character at once, including the originals, call GET /v3/avatars/looks?group_id=group_xyz789.

Send an Idempotency-Key header so a retry after a network timeout cannot start a second generation. The examples preserve their keys when rerun in the same shell; in an application, persist the key with the request so a restart can retry with the same key and body. Use a new key for each different request. While the original request is still in flight, a retry returns 409 with error.code of request_in_progress: wait, then retry. Once the original finishes, a retry within 24 hours replays its response.

Template access

A template id your workspace has access to resolves normally. One that belongs to another workspace returns 403, and an id that matches no template returns 400. Sending a pack id with type: "template", or a single template id with type: "look_pack", returns a 400 naming the method that would have taken it.