Core workflow

Sume workflows are usually small chains of read-only context calls, an explicit credit-spending create call, and job/result readback.

1. Read context

Start every integration by checking account, credits, and optional creative context.

sume me --json
sume credits --json
sume assets search "best product demo hooks" --limit 5 --json
sume tools list --json

API equivalents:

GET /me
GET /credits
GET /assets?q=best%20product%20demo%20hooks
GET /brand/current
GET /avatars

2. Choose inputs

Use the appropriate read endpoint before creating jobs:

Need	Read first
Brand tone, product claims, colors	`GET /brand/current` or `GET /brand?domain=...`
UGC/talking-head avatar	`GET /avatars` or `GET /avatars/{avatarId}`
Existing visual reference	`GET /assets?q=...` then `GET /assets/{assetId}`
Previous output	`GET /jobs/{jobId}/result`
Uploaded video	`POST /uploads/presign`, upload bytes, then feature-specific create/finalize call

3. Create work explicitly

Generation endpoints may spend credits, so agents should ask for confirmation unless the user has clearly authorized generation.

sume videos generate \
  --prompt "A creator opens with a skincare hook, then shows product texture." \
  --duration 4 \
  --resolution 480p \
  --json

Public API create endpoints:

POST /images/generations
POST /videos/generations
POST /ads/videos
POST /face-swap
POST /reference-analysis

4. Poll and fetch

sume jobs get <job_id> --json
sume jobs result <job_id> --json

Use --download only when the user wants files on disk:

sume jobs result <job_id> --download ./outputs/

5. Reuse outputs

Generated and uploaded videos can flow back into Asset Library after ingest. Search scenes by metadata and reuse the most relevant asset in the next generation or analysis step.

sume assets search "woman looking into camera opening hook" \
  --source-type generated \
  --max-duration 8 \
  --sort relevance \
  --json

Agent-safe rules

Prefer read-only calls while planning.
Do not ask the user for workspace ids; workspace scope comes from the API key.
Keep result payloads compact in user-facing summaries.
Redact API keys, signed URLs, request ids, user emails, workspace ids, and API key ids.
Do not call internal Sume routes, databases, provider APIs, deployment services, or Redis from agent workflows.