2026-10-02

Make an AI avatar video from the terminal with the Sume CLI

sume avatars create and sume avatar-videos create submit Avatar 1.0 jobs from a shell. Flags, the --confirm-paid guard, and how to recover the job.

4 min readSume

All posts

With the Sume CLI you make an avatar video in two commands: sume avatars create to make a reusable avatar and sume avatar-videos create to render a script with it. Both spend money, so both need --confirm-paid. The video command submits POST /v1/avatar-1.0/talking-video and, per the docs, checks locally that the script estimates to 4 to 60 seconds before it sends anything.

This suits shell scripts, cron jobs and agents that already run commands, and it keeps your API key out of hand-built curl lines.

The two commands

Create an avatar from text, wait for the job, then render.

sume avatars create \
  --confirm-paid \
  --avatar-handle studio_presenter \
  --type prompt \
  --prompt "A friendly presenter in neutral studio lighting" \
  --json

sume avatar-videos create \
  --confirm-paid \
  --avatar-handle studio_presenter \
  --script "Welcome to the weekly product update." \
  --quality standard \
  --json

Flags that matter

From the CLI docs, read 2026-10-01.

From CLI generation workflows and the CLI command reference.
Flag	Meaning
`--confirm-paid`	Required for generation that can reserve or spend credits
`--avatar-handle`	The handle to create or to render with
`--type`	`prompt`, `photo` or `props` for avatar creation
`--script`	Spoken script; must estimate to 4 to 60 seconds
`--quality`	`standard`, `plus` (default) or `max`
`--product-image`	Optional public HTTPS product image
`--payload-file`	Send an exact JSON body when flags are not enough

Recover and read the result

The submit prints a job envelope. Recover it with the jobs commands rather than submitting again:

sume jobs status job_123 --agent --json
sume jobs result job_123 --agent --json
sume jobs events job_123 --agent --json
sume avatars list --agent --json

When to use something else

Image, Video and Music generation have no CLI subcommand; call the API for them.
A server that must react the moment a video finishes should use a signed webhook rather than polling from a shell.
An agent in a hosted MCP client uses the MCP tools instead.

A habit worth keeping

Keep the avatar handle and the script in a file next to the command, not inline in shell history. A script file makes the 4 to 60 second check repeatable: if the estimate fails locally you fix the text and run again, and nothing was spent. When a run does go through, save the printed job id immediately, because sume jobs result is how you get the video URL back later.

Limits

Each video is 720p and 4 to 60 seconds. At the standard rate of $0.184 per second without a product image, a 15-second script costs $2.76, which is the figure to expect before you press enter on a loop. Check GET /v1/catalog for current rates, and do not wrap the command in a retry loop that changes the script: use the API with an Idempotency-Key if you need guaranteed single submission.