Jobs and results

Sume jobs represent asynchronous work such as image generation, video generation, AI Ads videos, Face Swap, Reference Analysis, and asset ingest.

When to use jobs

Use jobs whenever a create endpoint returns before work is complete. The initial response should give you a job id or a list of job ids. Store that id, then poll status and fetch results.

create endpoint -> job id -> GET /jobs/{jobId} -> GET /jobs/{jobId}/result

List recent jobs

curl "https://www.sume.so/api/v1/jobs?limit=5" \
  -H "Authorization: Bearer $SUME_API_KEY"

CLI:

sume jobs list --limit 5
sume jobs list --status completed --limit 5
sume jobs list --type video_generation --limit 5 --json

Supported list filters are limit, cursor, type, and status.

Poll one job

curl https://www.sume.so/api/v1/jobs/job_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

CLI:

sume jobs get job_123 --json

Polling guidance:

Status class	What to do
Queued/running/processing	Wait and poll again. Use longer intervals for video jobs.
Completed	Fetch the result.
Failed/canceled/expired	Stop polling and show the sanitized error/status.

Fetch results

curl https://www.sume.so/api/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

CLI:

sume jobs result job_123 --json
sume jobs result job_123 --download ./outputs/

Result payloads vary by job type. They can include generated media, Reference Analysis output, provider-safe metadata, or Asset Library ingest references.

Inline wait with CLI

For short jobs, the CLI can create and wait in one command:

sume images generate \
  --prompt "Clean product photo on a white bathroom counter." \
  --wait \
  --download ./outputs/ \
  --json

For longer jobs, avoid blocking the session:

sume videos generate \
  --prompt "Four-second product demo video." \
  --duration 4 \
  --resolution 480p \
  --json

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

Error handling

If a job fails, report:

• job id
• status
• sanitized error code/message if present
• request id if present

Do not print raw provider payloads, full signed/private URLs, or large transcript/media payloads into logs.