Trim, filter, or detach audio from a video with the Sume API

To trim, filter, or detach audio from a video with Sume, call one of three APIs: video trim cuts a [start, end) range into a new MP4, video filter dims, crops, or runs an allowlisted filtergraph into a new MP4, and audio detach extracts the audio track as a durable wav or mp3. Each takes one Sume-hosted clip and leaves the source untouched.

The facts below are from the Video trim, Video filter, and Audio detach docs, read on 2026-09-25.

What do trim, filter, and detach have in common?

The docs call trim and filter “Material preparation, not timeline placement”: sequencing, transitions, and the audio spine stay on Timeline 1.0 (see How to assemble a long-form video). All three share these rules:

• video_url must be your workspace's media.sume.com artifact or asset. Off-host URLs are rejected at admit; import first with POST /v1/media-imports.
• Every create requires Idempotency-Key. The default mode is async; mode: "sync" waits up to 30 seconds for a 200 finished job, otherwise you get 202 and poll.
• There is no per-tool GET. Poll GET /v1/jobs/:id/status and GET /v1/jobs/:id/result. On the hosted MCP server, call video_trim, video_filter, or audio_detach, then jobs_wait and jobs_result.
• The server compiles ffmpeg. Sending ffmpeg fields such as filter, ffmpeg, cmd, or codec returns ffmpeg_fields_rejected.
• Each is billed per job and runs worker ffmpeg only, with no provider inference; the filter check is free. Rates are on API pricing; confirm them in GET /v1/catalog.

How do I trim a clip?

Send video_url, start (seconds, ≥ 0), and exactly one of end or duration (0.2–900). An end past the source clamps, and the result warns trim_clamped_to_source.

precision: "exact" (the default) is a frame-accurate re-encode (libx264, yuv420p). "keyframe" is a stream copy, so the cut may start a GOP early; re-base against actual_start_seconds. audio is keep (default) or drop. An optional output of { width, height, fps } works with exact precision only: width and height 256–2160, fps 24, 25, 30, or 60.

The result (kind: video_trim) carries a new video_url, never the source, and actual_start_seconds. Drop that MP4 into timeline_create video[] with source_in 0.

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

How do I dim or crop a clip, and check the program first?

A filter program is ops[], a filters-only filtergraph, or both; ops[] runs first. Output inherits the source geometry, frame rate, and audio unless the program changes them.

To validate first, send the program to POST /v1/video-filter/check. It runs the same schema, op and filtergraph allowlists, and source preflight as the encode, and returns diagnostics instead of a 400: valid, diagnostics[], an estimate when valid, and next_action (submit_video_filter or fix_program_and_recheck). It creates no job, reserves no credits, and needs no Idempotency-Key. A program that passes can still fail on the box (bad expression, memory, time), as a structured job error.

• dim: whole-clip luma multiply, amount in (0, 1]. 0.45 is darker, 1 is unchanged, and black stays black.
• crop: a rectangle in fractions of the source frame. x and y in [0, 1], width and height in [0.05, 1], with x+width ≤ 1 and y+height ≤ 1.
• At most 8 ops.
• filtergraph: at most 2048 characters and 32 named filters, with no inputs, outputs, or paths. Only allowlisted tone, blur, geometry, fade, and internal compositing filters; trim, setpts, drawtext, subtitles, movie, lut3d, and anything that reads a file or a socket are not on the list.

curl -X POST https://api.sume.com/v1/video-filter/check \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "ops": [{ "op": "dim", "amount": 0.45 }]
  }'

How do I detach the audio track from a video?

The default output of POST /v1/audio-detach is sample-exact wav (pcm_s16le), which is what timeline_create audio.url, POST /v1/timeline-1.0/audio, and speech-to-text want. It returns a new audio_url.

• format: wav (default) or mp3 (128 kbps).
• range: optional { start, end? } in seconds. Omit it for the whole track, unless the track runs past 900 s.
• channels: source (default) or mono. sample_rate: 16000, 44100, or 48000; 16000 with mono is the STT shape.
• A source with no audio track fails detach_source_has_no_audio. Check probe.has_audio first with video inspect (frames: false is enough).
• For many ranges from one track, detach once, then split with timeline audio.

Why was my trim, filter, or detach refused?

• Trim: video_trim_range_required (neither end nor duration), video_trim_range_conflict (both), video_trim_range_empty (end ≤ start, or longer than 900 s), video_trim_output_requires_exact, and source_duration_exceeded (source longer than 1800 s).
• Filter: video_filter_ops_empty, video_filter_too_many_ops, unsupported_filter_op (only dim and crop), video_filter_amount_out_of_range, video_filter_crop_out_of_bounds, invalid_filtergraph, source_too_large, and output_duration_exceeded (source longer than 300 s).
• Detach: audio_detach_range_empty, detach_source_has_no_audio, and detach_start_past_source.
• All three: unsupported_media_source (not on the Sume media host), source_not_found (a dead or foreign media.sume.com URL), and unsupported_media_type (HEAD is not a video).