HeyGen Studio Templates API vs a reusable Sume avatar request

HeyGen's October 2026 changelog adds POST /v3/templates, which turns a generated or saved video into a private template with bindable variables. Sume's docs describe no template resource for avatar videos: the reusable parts are the avatar handle and the request body your code keeps.

If your goal is one design producing hundreds of personalised clips, both can get you there. The state lives in different places.

What does HeyGen's template API do?

From the changelog entry: POST /v3/templates converts a generated or saved video into a private template. GET /v3/templates/{template_id} returns the composition, including element IDs and bindable properties, plus an edit version. PUT /v3/templates/{template_id}/variables defines the variable list, and passing expected_edit_version gives conflict detection: a stale version returns 409 stale_edit_version.

In short, HeyGen stores the design server-side and you bind values to it.

What is the reusable unit on Sume?

Two things persist. First, the avatar: POST /v1/avatar-1.0/generate makes a reusable avatar from a prompt, a profile (props), or a reference image (photo), keyed by an avatar_handle that Sume stores without any leading @. Second, the request body, which is plain JSON you own. Avatar video takes exactly one of script or video_inputs, plus optional product_image, scene, quality and aspect_ratio.

Nothing in the docs we read stores a layout with named placeholders on the server. Variables are whatever your code substitutes before sending.

How do I template a body myself?

Keep one function that builds the body from a record and send it with a per-record idempotency key. This sketch needs only the standard library and a SUME_API_KEY environment variable.

The key matters: reusing a key for a different payload returns 409 idempotency_conflict, while an exact retry does not create a second paid job.

import json, os, urllib.request

def build(row):
    return {"avatar_handle": "sume_clawra", "quality": "plus",
            "script": f"Hi {row['name']}, your {row['plan']} plan renews on {row['date']}."}

def submit(row):
    req = urllib.request.Request(
        "https://api.sume.com/v1/avatar-1.0/talking-video",
        data=json.dumps(build(row)).encode(),
        headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"],
                 "Content-Type": "application/json",
                 "Idempotency-Key": f"renewal-{row['id']}"},
        method="POST")
    with urllib.request.urlopen(req) as r:
        return json.load(r)

print(submit({"id": 1, "name": "Ada", "plan": "Pro", "date": "Nov 3"}))

How do the two models differ?

Read the differences as trade-offs, not a scorecard.

What about voice and look consistency across records?

Because the avatar is a stored resource, every record rendered with the same avatar_handle reuses the same identity. Create it once, wait for the job to complete, and only then submit videos: using an avatar that is not ready returns 409 avatar_not_ready and creates no job. The docs describe a handle rather than a per-template voice binding, so treat voice as part of the avatar rather than a variable you rebind per request.

If you want a different look, the documented route is a new avatar handle. That is a different model from HeyGen's look packs, which dress an avatar you already own.

What should you do on Sume today?

Preview one representative record with Avatar video previews, approve it, then loop the rest. Structural fields such as script, video_inputs, avatar_handle, scene and aspect_ratio need a new preview if they change, while quality can be overridden at generate-video.

For retries and double-billing protection see retry an avatar video request without double billing. For queue behaviour on large loops, read Generation admission.