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.
API equivalents:
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.
Public API create endpoints:
4. Poll and fetch
Use --download only when the user wants files on disk:
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.
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.