|Docs

Generation workflows

Generation and analysis commands create async jobs through the Sume Public API. They can spend credits or create provider work. Agents should confirm explicit user intent before running them.

Start with:

Image generation

Create a job:

Wait and download:

Use Brand reference images returned by Sume:

Image options:

OptionNotes
--prompt <prompt>Required.
--aspect-ratio <ratio>1:1, 4:5, or 9:16.
--n <count>Currently 1 reliable output per job.
--resolution <resolution>Sume-supported image resolution.
--quality <quality>Sume-supported image quality.
--reference-image-url <url>HTTPS image reference URL. Repeat for multiple references.
--wait / --timeout <seconds>Poll until terminal. Default timeout: 600 seconds.
--download [path]Wait and download safe public output URLs.

Video generation

Video duration is validated by the CLI: 4 to 15 seconds.

Video options:

OptionNotes
--prompt <prompt>Required.
--aspect-ratio <ratio>For example 9:16.
--duration <seconds>4 to 15 seconds.
--resolution <resolution>480p or 720p.
--generate-audioAsk Sume to generate audio if supported.
--wait / --timeout <seconds>Poll until terminal. Default timeout: 1800 seconds.
--download [path]Wait and download safe public output URLs.

Use avatars from sume avatars list:

Create a talking-head style ad job:

Create a UGC-style ad with references:

Paid Ads jobs are async. Read results with jobs.

Face Swap

Face Swap requires an uploaded Sume media URL with purpose face_swap_source_video.

  1. Presign the upload:

  1. Upload bytes to the returned signed upload_url with only required_headers.

  2. Create the Face Swap job:

Face Swap can accept repeated --avatar-id values. The CLI waits on the primary returned job when --wait is set.

Reference Analysis

Reference Analysis accepts public TikTok or Instagram Reel URLs:

Wait for the result:

Reference Analysis jobs can take longer than image generation. If an agent cannot wait safely, create the job, store the job id, and poll with jobs.

For long-running jobs:

For MCP clients, use jobs.wait when the host has exposed the default read toolset.

Safety checklist

Before running any create command from an agent:

  • confirm the user asked for generation or analysis;
  • check sume credits --json;
  • use placeholders in examples, not real private media URLs;
  • prefer --json and summarize results;
  • do not log full provider payloads or signed upload URLs;
  • stop on clear API errors instead of retrying paid work blindly.