Batch video processing by API: one edit, many videos

Batch video processing means applying the same edit (a cut, a crop, a resize, a logo) to many videos without handling each one by hand. With an API, a batch is a loop: your script submits one job per file with the same settings, the service queues what it can't run yet, and you collect each result as it finishes.

On Sume the single-clip edit tools have no batch endpoint, so the loop is yours. The facts below come from the Video trim, Video filter, Timeline compose, Jobs and results, and Generation admission docs, read on 2026-09-29. Anything described as current behavior is read from Sume's code.

Which videos can a Sume batch process?

Files already in your Sume workspace on media.sume.com, such as the outputs of earlier Sume jobs. Trim, filter, and compose reject off-host URLs, and there is no public upload route for files on your computer. That makes Sume a fit for batches of videos it made (generated clips, captioned clips, renders), not for a folder of your own footage.

Which edit uses which endpoint?

Each job takes one clip and returns a new MP4; the source is untouched.

How do I run the batch?

Check the edit once, then loop. To resize a clip without changing its shape, trim it over its full length with output set to the new width and height; the loop below does that. For a filter program, POST /v1/video-filter/check is free and returns diagnostics without creating a job. The docs note a program that passes can still fail on the worker, so render one real clip before the rest.

In the loop, give every file its own Idempotency-Key derived from the file, so a retried request can't create a second job. Reuse a key only for the same operation and payload. Send a webhook_url and each job calls you once when it completes, fails, or is canceled.

import os, requests

API = "https://api.sume.com/v1/video-trim"
HEADERS = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

clips = {  # your id -> (Sume-hosted source, length in seconds)
    "clip-001": ("https://media.sume.com/artifacts/artf_demo/a.mp4", 42.0),
    "clip-002": ("https://media.sume.com/artifacts/artf_demo/b.mp4", 18.5),
}

jobs = {}
for clip_id, (url, seconds) in clips.items():
    body = {
        "video_url": url,
        "start": 0,
        "duration": seconds,  # the whole clip
        "output": {"width": 720, "height": 1280},  # same 9:16 shape as the sources
        "webhook_url": "https://example.com/hooks/sume",
    }
    r = requests.post(API, json=body, headers={
        **HEADERS, "Idempotency-Key": f"resize-720-{clip_id}"})
    r.raise_for_status()
    jobs[clip_id] = r.json()

How many jobs run at once?

Your workspace's concurrency limit decides. Jobs past it wait as queued and start as slots free up; once the queue is full too, a new submit gets 429 queue_full. Video job concurrency and queueing covers the limits and how to size a batch, and which calls take a slot lists the job types that count.

In current code a retry with the same key after queue_full replays the refusal, so pace the loop, wait for jobs to finish, and submit that file again with a new key.

How much does batch video processing cost?

Each job is billed on its own. 200 clips resized with one trim each reserve at most $4.00, plus a 5.5% agent fee by default. Each tool reserves its listed rate and captures its own compute, never above the reservation.

• Trim: source up to 1,800 s, output 0.2–900 s; output needs precision: "exact".
• Filter and compose: source or output up to 300 s.
• Webhooks are terminal-only and signed. Verify each delivery, and keep polling GET /v1/jobs/:id/status as a backup (signed webhooks).