Find the avatar handle for sume avatar-videos create (--agent --json)

To get the handle that sume avatar-videos create --avatar-handle needs, run sume avatars list --agent --json, or sume avatars get <avatar_id> --agent --json for one avatar. Then submit the video with --confirm-paid, because it can spend credits.

The commands come from the CLI generation workflows and command reference pages, read 2026-10-02.

Why does the CLI need a handle at all?

Avatar 1.0 is a two-step workflow: create a reusable avatar, then use it to generate talking videos. The handle is the stable name you chose at creation, such as studio_presenter. It may be typed with a leading @, but Sume stores it without one.

The CLI submits POST /v1/avatar-1.0/talking-video for videos and POST /v1/avatar-1.0/generate for avatars. A video request against an avatar that is not ready yet is not something to hope works; wait for the avatar job to finish first.

What do --agent and --json change?

--json gives stable machine-readable output. --agent is for automation reading output that may contain sensitive URLs or account metadata; the CLI overview recommends it in that case. Docs examples for reading handles pair them, so use both in scripts.

What does a full terminal session look like?

Log in, read the handles, submit the video, then recover the job with the same CLI.

sume login
sume avatars list --agent --json
sume avatar-videos create \
  --confirm-paid \
  --avatar-handle sume_clawra \
  --script "Say hello to the Sume developer platform." \
  --quality plus \
  --json
sume jobs status job_123 --agent --json
sume jobs result job_123 --agent --json

The job id in the last two lines is a placeholder; use the one the create command prints.

Which limits does the CLI enforce before submit?

The script must estimate to 4 to 60 seconds inclusive, and the CLI validates this before submission, so a too-long script fails locally instead of at the API. quality accepts standard, plus or max, and when omitted it defaults to plus, the same as the API. Use --quality standard for the fastest path, or max when quality matters more than turnaround.

You can add --product-image with a public HTTPS URL for a product shot. For anything the flags do not cover, --payload-json or --payload-file sends an exact request body.

What can the CLI not do?

Avatar is the only first-class generation submit path in the CLI today. There is no sume image, sume video or sume music; those go through the HTTP API, and afterwards you can still recover them with sume jobs status, sume jobs result and sume jobs download.

Batch helpers exist under sume avatars batch and sume avatar-videos batch, working against local state files; run sume avatars batch --help to see them, since the docs do not list their flags. Writes need confirmation: --confirm-paid when execution may spend credits, --confirm-submit for non-paid writes such as cancellation.

Common mistakes

Three errors account for most failed first attempts. First, passing an avatar id where a handle is expected: sume avatars get takes the id, while --avatar-handle takes the handle. Second, forgetting --confirm-paid, which the CLI requires because provider execution may spend credits. Third, submitting a script that estimates over 60 seconds; the CLI stops it before submit, so split it into several jobs.

If a command seems to hang, remember that creation is job-backed. The create command submits and returns a job; it is sume jobs status and sume jobs result that tell you when the avatar or video is done. For a progress timeline, sume jobs events job_123 --agent --json reads the public events.

Finally, keep handles short and lowercase with underscores, as in the docs' studio_presenter, and read the naming rules post before you automate creation.