Try Avatar 1.0 in the Sume playground before you write any code

Open the Sume Avatar playground at sume.com/playground, run one small avatar request signed in to your workspace, and copy the payload that worked into curl, the CLI or your server code. The docs describe it as a human-operated way to try Avatar generation, meant for validating payloads before you automate them.

The playground is not a separate API. It exercises the same Avatar 1.0 routes the Avatar guide documents, so a body that works there is the body to send elsewhere.

What should your first playground run be?

Make it the cheapest useful thing: create one avatar from a short prompt. Every Avatar job is paid, so one bounded run beats a batch. The request has a top-level avatar_handle and an input union with type prompt, props or photo. The playground lets you see which of those your inputs fit before you commit.

How do you move the payload out of the playground?

Take the JSON body unchanged. For curl, add the bearer header and an Idempotency-Key. For the CLI, the same create is sume avatars create --confirm-paid --avatar-handle studio_presenter --type prompt --prompt "Friendly studio presenter" --json, which submits POST /v1/avatar-1.0/generate. For exact fields, check the live OpenAPI schema, or sume tools schema avatars.create --json.

curl -X POST https://api.sume.com/v1/avatar-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: playground-copy-001" \
  -d '{"avatar_handle":"studio_presenter","input":{"type":"prompt","prompt":"Friendly studio presenter"}}'

What comes after the avatar is ready?

Poll the job at /v1/jobs/:id/status, then read /v1/jobs/:id/result once it is completed. Only then use the handle on Generate avatar video, where the script has to estimate to 4-60 seconds. Rendering before the avatar is ready is a common first mistake; wait for the avatar job instead of retrying.

If you want to look at composition before paying for the full render, create an avatar video preview, which stops at first-frame stills.

What does the playground not replace?

It does not replace server-side error handling, retries with idempotency keys, or webhooks, and it is for a signed-in human rather than a deployed integration. The docs also point to the OpenAPI schema for exact request and response fields, because the schema is the contract. Treat the playground as a quick check, then read the schema before you ship.

Can an AI agent use the same payload?

Yes. The hosted MCP server lists the avatar tools, and the paid ones need confirmation before they spend credits. The CLI requires --confirm-paid for Avatar and Avatar Video runs. The safe pattern is the same everywhere: validate the payload, ask for confirmation, submit one bounded job, and recover through job status and events instead of blindly retrying a paid command.

If a job stalls, read GET /v1/jobs/:id/events for the public timeline. Events do not expose raw provider task ids or raw provider URLs, so they are safe to paste into a ticket.