Four avatar clips a week: Python batch, one idempotency key each

To post an avatar clip every week without redoing the setup, keep one ready avatar handle and submit a small batch of POST /v1/avatar-1.0/talking-video calls, each with an Idempotency-Key built from the ISO week and the clip's position. A retry with the same key and body is safe; a different body under the same key is rejected as a conflict.

The nudge is in HeyGen's The State of AI Avatars 2026 (September 2026, 1,000+ small business owners): among avatar users, 71.1% said they saved time, 55.3% post more often, and 43.6% post more consistently. It is a vendor's survey of its own users. The batch below is a way to make consistency cheap and repeatable on Sume; it does not guarantee any of those outcomes.

What goes into the key?

Make the key deterministic so that rerunning the script after a crash does not create duplicates, and unique so that next week's clip does not collide. A week stamp plus an index does both: weekly-2026-W41-0, weekly-2026-W41-1. If you edit a script after submitting, bump a version suffix, because the same key with a changed payload returns 409 idempotency_conflict.

How should the batch handle queue_full?

Sume accepts only so many paid generation jobs at a time. When the workspace has no remaining accepted capacity, a submit fails with 429 queue_full, and the documented fix is to wait for jobs to finish and retry with the same idempotency key. A weekly batch of four rarely hits it, but a shared workspace might.

Submit responses include generation_limits when Sume can compute it, with a queue_capacity_remaining count. Treat it as a snapshot, not a promise.

What does the script look like?

The loop below stops at the first 429 so it does not hammer a full queue. Rerun it later with the same week and it will resume safely, because the keys are the same.

import datetime
import os
import requests

URL = "https://api.sume.com/v1/avatar-1.0/talking-video"
HEADERS = {
    "Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
    "Content-Type": "application/json",
}
SCRIPTS = [
    "Monday: what is on this week.",
    "Wednesday: one tip from a customer question.",
    "Friday: what shipped and what is next.",
    "Saturday: a quick behind the scenes note.",
]
year, week, _ = datetime.date.today().isocalendar()

for i, script in enumerate(SCRIPTS):
    key = f"weekly-{year}-W{week}-{i}-v1"
    body = {"avatar_handle": "shop_owner", "script": script,
            "aspect_ratio": "9:16", "mode": "async"}
    r = requests.post(URL, headers={**HEADERS, "Idempotency-Key": key},
                      json=body, timeout=30)
    print(key, r.status_code)
    if r.status_code == 429:
        break

How do you collect the results?

Each submit returns a job. Poll /v1/jobs/:id/status or use a webhook, then read the result; do not use mode: sync for a render, because the server-side wait is capped at 30 seconds. For four clips a week, polling once a minute is plenty.

What does this not do?

It does not write the scripts, schedule the posts or publish anything; it only renders. It also uses one avatar for the whole batch, since a final video resolves to one avatar. Each script still has to estimate to 4-60 seconds, so keep them short.

What should you store between runs?

Keep the week stamp, each key, and the job id from each response. The job id is what you poll later, and the key is what makes a rerun safe. If a run dies halfway, rerun the script: keys that already succeeded are returned as the same job, and the rest are submitted.

Keep each script's text next to its key. Reusing a key with a changed script is a conflict, so a text edit needs a new version suffix.