Check an Avatar payload with sume tools schema before --confirm-paid

Before you pass --confirm-paid to sume avatar-videos create, run sume tools schema avatar-videos.create --json to see the exact fields the command accepts. It is read-only, it costs nothing, and it replaces guessing at flag names from an old example.

The command reference says to discover exact schemas at runtime with sume tools list --json and sume tools schema <name> --json, and the jobs and media page uses the same two schema commands for Avatar generation. This post turns that into a repeatable check.

Why check the schema first?

Avatar generators are the only first-class generation submit path in the CLI, and they can reserve or spend credits. The CLI gates that with --confirm-paid. A wrong field name or a rejected media URL costs a round trip at best, and at worst you discover the mistake after a paid job has started.

A schema read has no side effect. It also stays correct when the CLI changes, because it comes from the binary you have installed rather than from a blog post. Run sume version alongside it so your notes say which release the schema came from.

What is the read-only loop?

The CLI's recommended loop for agents is: inspect catalog and local readiness, validate the payload with a read-only or schema command, ask for confirmation before writes or paid work, submit one bounded job, then recover through the job commands.

Every step before the submit is free:

sume version
sume doctor --agent --json              # local readiness, no API call
sume tools list --json                  # what tools exist
sume tools schema avatar-videos.create --json
sume tools schema avatars.create --json
sume balance                            # is there money to spend

# only now, with a human's yes:
sume avatar-videos create --confirm-paid \
  --avatar-handle sume_clawra \
  --script "Say hello" --quality plus

What constraints are documented outside the schema?

A few rules live in the docs rather than in field names. Avatar Video scripts must estimate to 4 to 60 seconds inclusive before submission, and quality defaults to plus when omitted, with standard and max as the other values. Media fields such as --image-url, --product-image and --scene-image-url expect public HTTPS image URLs.

The troubleshooting page lists why a media input is rejected: the URL is not HTTPS, it points at localhost or a private network, the response is not an image, or it needs cookies, auth headers or a short-lived signature that expires before Sume can fetch it. None of those is visible in a schema, so test the URL from a machine outside your network first.

What if the command is not there?

Then it does not exist yet. The CLI ships no sume image, sume video or sume music; sume tools list --json will not show them either. For those families call the Developer API, and use sume jobs status, jobs result and jobs download to recover the job.

If a paid command times out locally, inspect the job with sume jobs status <job_id> --agent --json before submitting again, since the job may already exist and be billing. The security page advises submitting one bounded job first when testing and recovering existing jobs instead of retrying paid commands blindly.

How do agents fit into this?

The CLI is built so an AI agent can drive it safely, and the schema check is the step that makes that practical. Have the agent run sume tools list --json and sume tools schema <name> --json itself, then show you the exact command it intends to run before you approve it. Because those commands are read-only, you can let an agent run them freely and keep your approval for the line that has --confirm-paid in it.

Use --agent --json on every read so the output is redacted of URL-like and account or workspace fields where supported. The agent-safe guidance also says to summarize outputs without pasting secrets or signed URLs, and to submit one bounded job at a time. If an agent proposes a batch, use the batch helpers' plan step first: sume avatars batch and sume avatar-videos batch have plan, create, watch and result subcommands over local state files, and --help shows their flags.

A last habit: record the schema output in the pull request or ticket next to the command you ran. When someone later asks why a job was submitted with a given quality or script, you have the contract it was checked against.