Five-lesson avatar onboarding series: one handle, safe retries

A good onboarding series is five short lessons with one presenter, each rendered as its own Sume avatar video. Create one avatar, reuse its handle for every lesson, send each script with its own idempotency key, and approve a preview before the full render. Each lesson stays inside the accepted 4 to 60 second window.

Plan the series

Keep one idea per lesson and write the scripts first. A table keeps the plan honest.

Create the presenter once

Make the avatar with POST /v1/avatar-1.0/generate, from a prompt, structured traits or a reference photo, and poll the job to completed. Pick a handle that fits the 2 to 30 character rules, such as acme_guide_v1. Only use a reference photo of a person who has agreed to it.

Render each lesson

Call POST /v1/avatar-1.0/talking-video per lesson with the same avatar_handle, a script, an aspect_ratio that fits where it is shown (default 9:16), and a quality (default plus). Put the lesson number and series version in the idempotency key. If your process restarts, resending the same key returns the first job instead of starting and billing a second one.

• Create a preview first for lesson 1, since it sets the look for the series.
• Turn on inline captions with a style that suits your audience; Korean scripts need a Hangul style, and Sume rejects slam, punch and tiktok-green for them.
• Store each job id against its lesson row.
• A caption-stage failure is soft: the video can still succeed with a clean file.

Publish and maintain

Completed results include public media.sume.com URLs, so embed them directly or download and host them yourself. When a product screen changes, change only that lesson's script, bump its key to v2, and render again. The other four videos stay as they are, and the presenter looks the same throughout.

If you need the lessons assembled into one longer video, that is a separate step; each avatar job here makes one clip. A single script over 60 seconds must be split into multiple jobs.