HeyGen drops avatar_look_id on Oct 31: what to store on Sume

HeyGen's API changelog lists avatar_look_id, character_id and character_type as deprecated effective October 31, 2026, and tells integrators to move to avatar_id (HeyGen API changelog, read 2026-10-10). A Sume Avatar 1.0 integration has no look or character-type field to migrate: you name each avatar with an avatar_handle when you create it, and every talking video points at that handle.

That makes this deprecation a good moment to check what your own database stores. If a column holds a vendor look id that will stop working in three weeks, you want to know which column it is before the date, not after. This post maps the three deprecated fields to what Sume keeps, using the Create new avatar and Generate avatar video pages.

What the HeyGen entry says

The deprecation sits inside HeyGen's October 2026 entry about creating Studio templates through the API (POST /v3/templates, plus PUT /v3/templates/{template_id}/variables to declare bindable elements). The same entry lists the three deprecated fields and names avatar_id as the migration target. I did not read HeyGen's reference for what each field meant, so the table repeats only what the changelog states.

How Sume names an avatar

Sume creates an avatar with POST /v1/avatar-1.0/generate. The body has a top-level avatar_handle and an input union: a text prompt, structured traits (props), or a reference photo (photo, with a public HTTPS image_url). The handle can start with @; Sume normalizes it and stores it without the @.

Creation is a job. You poll GET /v1/jobs/{id}/status, then read the result, which returns the avatar handle or a resource id. After that, GET /v1/avatar-1.0/avatars lists your avatars and GET /v1/avatar-1.0/avatars/{id} reads one. The older GET /v1/avatars routes still answer with the same shape.

A talking video then uses the top-level avatar_handle, or per-scene character fields inside video_inputs. The Avatar docs define no look concept and no character-type field.

What to store

Treat the handle as your primary key for an avatar and keep the resource id next to it, because the list and read routes use the id. If you used HeyGen looks as outfits or settings of one person, the straightforward Sume model is one avatar per look, each with its own handle, since the docs show nothing finer-grained than a handle.

Where a one-avatar-per-video limit bites

If your HeyGen templates switched characters between scenes, check this before migrating. The Avatar Video docs say the current execution supports one resolved avatar for each final video, and that scene backgrounds are expected to resolve to one shared scene. A two-person dialogue therefore becomes two jobs. Sume's timeline compose page says assembly of several shots stays on Timeline 1.0, so the join happens there, not inside the avatar request. Plan the cut points before you write the scripts, because each job needs its own script and each script has its own duration window.

The same single-avatar rule affects how you store history. If you keep a record of which avatar spoke in each finished video, one row per final video is enough on Sume, and a multi-speaker piece is a list of such rows joined by your own project key.

• Run one talking-video job per speaker, each with its own avatar_handle.
• Keep each job inside the 4 to 60 second window the Avatar Video docs state.
• Assemble the clips on Timeline 1.0 and add the music or room tone there.

A short check before October 31

Search your code and tables for the three deprecated names, then list your Sume avatars to confirm each stored handle resolves. The commands below do both on the Sume side; the key stays in the environment.

# list avatars, then request a short talking video with a stored handle
curl -sS https://api.sume.com/v1/avatar-1.0/avatars \
  -H "Authorization: Bearer $SUME_API_KEY"

curl -sS -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: handle-check-001" \
  -d '{"avatar_handle":"product_host","aspect_ratio":"9:16","quality":"standard",
       "script":"Quick check that this handle resolves before the migration date."}'