Fast video cut API: precision keyframe and actual_start_seconds

To cut a clip quickly with an API, send precision: "keyframe" to POST /v1/video-trim. Sume copies the stream instead of re-encoding it, but the cut can start one GOP early, so read actual_start_seconds from the result and re-base your times against it. The default, exact, is a frame-accurate re-encode. Both cost $0.02 per job.

Exact versus keyframe

The trim input is a media.sume.com clip in your workspace, a start in seconds, and exactly one of end or duration. The source is never changed; the result is a new MP4.

Re-basing after a keyframe cut

The docs say a keyframe cut "can start a GOP early". On typical sources the Video inspect page puts a keyframe snap at roughly 0 to 5 seconds, though that figure is for stills, not trims, so treat it as an order of magnitude. The safe pattern is to read the real value.

The result carries video_url, duration_seconds, actual_start_seconds, precision, and audio. Suppose you asked for start: 12, and actual_start_seconds came back lower. Every caption cue or overlay time you planned relative to second 12 must be shifted by the difference. If you then place the clip in a timeline render, use source_in: 0 on the new file, as the docs suggest.

curl -X POST https://api.sume.com/v1/video-trim \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trim-fast-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "start": 12,
    "duration": 20,
    "precision": "keyframe"
  }'

When to choose which

Pick keyframe for rough cuts, previews, or when you will trim again later. Pick exact when the cut point matters, such as removing a claimed song bar, or when you need the output conform to set width, height, or frame rate. Because both modes bill $0.02 per job, there is no price reason to prefer the fast one; the difference is accuracy and whether re-encoding is acceptable.

Clamping works the same way in both: an end past the source end clamps and the result warns trim_clamped_to_source. The output must be at least 0.2 seconds and at most 900 seconds.

Worked example of a re-base

Say you request start: 12 and a 20-second duration with keyframe precision, and the result reports an actual_start_seconds of 10.0 (an illustrative value, not a measurement). The file now begins two seconds earlier than you asked. A caption cue you planned for second 3 of your intended cut is at second 5 of the new file, so add the 2-second difference to every time you planned.

The cleanest alternative is to avoid the problem. If your next step needs times that are exact to the frame, such as burning cues or aligning to an audio spine, use the default exact mode at the same $0.02 price. Use keyframe only when a rough cut is acceptable or you will trim again.

Submit and read

The default mode is async. Pass mode: "sync" to wait up to 30 seconds for a 200; otherwise you receive 202 and poll GET /v1/jobs/:id/status and then GET /v1/jobs/:id/result. There is no GET /v1/video-trim/:id.