A video trimming API for frame-accurate trim, stitch and splice

Trim an upload while it is encoded

To keep one part of a new upload, add a trim object with start and end in seconds to the complete call. The trim is frame-accurate and costs no extra processing time, because it is applied during the normal encode rather than as a second pass. Every chunk seeks to the trim offset plus its own start, and the audio drops the same span, so picture and sound stay together.

The trim is remembered: reprocessing a trimmed video keeps its trim, and redaction times are measured on the trimmed timeline. For a video you have already processed, use an edit instead.

Stitch, splice and cut out with edits

An edit makes a new video from clips of your finished videos. There is nothing to upload: you send POST /videos with an edit instead of a file, and poll the new video as usual. Each clip has:

• videoId, one of your finished videos. The same video may appear more than once.
• start and end, in seconds into that video (decimals allowed; the default is the whole video).
• transition, how the clip begins from the previous one: omit it for a hard cut, or use fade (a crossfade) or fadeblack (a fade through black) with a length from 0.1 to 3 seconds.

An edit can hold up to 50 clips. The first clip sets the frame size and differently shaped clips are letterboxed; the edit runs at the fastest clip's frame rate. Every clip is cut to whole frames and gets audio of exactly its length, and a clip with no audio plays silence. The timeline is rendered into one near-lossless intermediate file, then the normal pipeline encodes it, so redactions and captions can be applied on the edit's own timeline.

Recipes

These come straight from the documentation. Because a clip can reuse the same video, three patterns cover most editing:

// Cut 1:00-1:30 out of a video
{ "edit": { "clips": [ { "videoId": "AAAA…", "end": 60 }, { "videoId": "AAAA…", "start": 90 } ] } }

// Stitch an intro, a lesson and an outro, with soft joins
{ "fileName": "Lesson 1", "edit": { "clips": [
  { "videoId": "INTRO…" },
  { "videoId": "LESSON…", "transition": { "type": "fade", "seconds": 0.75 } },
  { "videoId": "OUTRO…",  "transition": { "type": "fadeblack", "seconds": 1 } } ] } }

// Splice a clip into another at 2:00
{ "edit": { "clips": [
  { "videoId": "MAIN…", "end": 120 },
  { "videoId": "INSERT…", "transition": { "type": "fadeblack", "seconds": 0.5 } },
  { "videoId": "MAIN…", "start": 120, "transition": { "type": "fadeblack", "seconds": 0.5 } } ] } }

Send any of them with a normal authenticated request:

curl -s -X POST "$VIDEO_API/videos" \
  -H "Authorization: Bearer $VIDEO_API_KEY" -H "Content-Type: application/json" \
  -d '{"edit":{"clips":[{"videoId":"AAAA…","end":60},{"videoId":"AAAA…","start":90}]}}'
# 201 Created
# { "videoId": "9a8b…", "status": "SUBMITTED", "clips": 2, "statusPath": "/videos/9a8b…" }

Check an edit before you run it

Requests are validated against your videos' real lengths, so a trim past the end of a video, a clip that doesn't fit or a transition longer than its clips is refused with every problem listed at once and its field path. Add ?dryRun=true to see whether an edit is valid, and how long it will be, without creating anything. A clip from someone else's video answers 404 NOT_FOUND; a source that is still processing answers 409 EDIT_SOURCE_NOT_READY.

A timeline editor, if you want a UI

The same operations are available in a drag-and-drop timeline editor in the web app: reorder clips, drag their edges to trim, split at the playhead, cut out a section with In and Out pins, and cycle each join between cut, crossfade and fade to black. Every gesture produces exactly the clips the API takes. You can also put that editor on your own site with the video editor web component, which saves the result as one new video in your account.

What it costs

An edit costs one extra encode pass, which is about 3 to 5 times faster than real time, and its minutes are counted on the finished output. Trimming and cutting sections out therefore reduce what you pay, because you only pay for the video you keep. See the transcoding API for how quality levels are counted.

Which plans include trim, stitch and splice

Trimming, stitching and splicing are part of the core API on every plan, including Free. The finished video is made at your plan's top quality or lower, and counts toward your processing minutes by its output length.

Usage beyond a paid plan is billed at $0.09 per processing minute, $0.15 per GB-month of storage and $0.55 per GB of delivery. Full details are on the pricing page.

In the documentation

• Processing options (trim)
• Trim, stitch and splice (edits)
• Validation and dry runs
• The video-piper-editor web component
• Usage and billing

Frequently asked questions