Change a video's frame rate or resolution with the Sume API

To change a video's frame rate or resolution with the Sume API, re-encode the Sume-hosted clip with POST /v1/video-trim and an output of { width, height, fps }, or run the allowlisted scale and fps filters through POST /v1/video-filter. Timeline 1.0 and timeline compose also take an output size and rate, and a render picks its frame rate from the sources when you omit one.

The facts below come from the Video trim, Video filter, Timeline 1.0, and Timeline compose docs and the Sume API reference, read on 2026-09-26. Behavior read from Sume's media compiler is described as it works today.

Which tool changes size or frame rate?

All four read only your workspace's media.sume.com artifacts or assets. To see a clip's current size and rate first, run a free inspect probe; see Get a video's duration, resolution, and fps.

How do I resize or retime a clip with video trim?

Trim's output conform works only with precision: "exact", the default; with keyframe it is refused as video_trim_output_requires_exact. Omit it and the clip keeps the source size and rate. Today, setting only width or only height keeps the aspect ratio, setting both scales the clip to exactly that size, and sizes are rounded down to even pixels. To conform a whole clip, cut from start: 0 to its full length (at most 900 seconds). Trim, filter, or detach audio covers the rest of trim.

curl -X POST https://api.sume.com/v1/video-trim \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conform-720p30-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "start": 0,
    "end": 42,
    "output": { "height": 720, "fps": 30 }
  }'

Can video filter change the frame rate?

Yes. scale, fps, and framerate are on the filtergraph allowlist, so a program such as "filtergraph": "scale=1280:720,fps=30" changes both; without them, a filter output keeps the source's geometry and frame rate. The source can be at most 300 seconds. Validate the program for free with POST /v1/video-filter/check first; the filter allowlist post lists every allowed name.

How does Timeline pick an output frame rate?

output.fps takes 24, 25, 30, or 60. Omit it and the render uses the rate the sources already run at. Today that works like this:

• Each clip's probed rate snaps to the nearest of the four values, and the rate that the most seconds of video run at wins. A tie goes to the higher rate. Stills have no rate, and 30 applies only when nothing has one.
• A source within 0.05 fps of the output counts as a match and draws no warning: 29.97 fps footage renders at 30, and 23.976 at 24.
• Any other mismatch repeats or drops a frame every few frames, which shows as judder on motion: 24 fps footage at 30 repeats one frame in five, and 25 fps footage one in six. The result warns output_fps_resamples_sources with the rate the sources wanted.

How do I avoid scaling a clip twice?

Conform once, to the size you will assemble into. The API reference says to set trim's output to the timeline you assemble into, and the compose docs say the same for compose's output.width and output.height. Compose defaults to the video layer's own frame rate, the only rate that repeats or drops no frame; an explicit output.fps that differs warns output_fps_resamples_sources.

What does it cost?

Trim, filter, and compose are priced per job, and GET /v1/catalog lists the live rates; the filter check and the inspect probe are free. The API pricing rate card lists a Timeline render at $0.10 per output minute, and a render reserves ceil(audio.duration_seconds / 60) minutes. None of these tools runs provider inference; they run worker ffmpeg only.