Video trim
Cut a [start, end) range out of one Sume-hosted clip into a new MP4. Material preparation, not timeline placement.
Current SoT. Media L2 range cut (
sume/video-trim-1.0, #5953). It is available on dest and prod. This API does not inspect a clip. For clip inspection, use video inspect. This API does not assemble clips. The clip sequence, transitions, and the audio spine stay on Timeline 1.0.
Video trim 1.0 uses one workspace media.sume.com clip and a range as
input. It returns a new MP4 artifact that contains only [start, end).
The source does not change. The server compiles ffmpeg on the worker media
runtime (apps/api/src/routes.ts createVideoTrimV1 /
submitSumeVideoTrimJob).
There is no GET /v1/video-trim/:id. Poll the job envelope:
Hosted MCP: video_trim (packages/mcp-server/src/mcp.ts). A write must
have idempotency_key (and mcp:write under OAuth). Flow: video_trim →
jobs_wait → jobs_result.
Create a trim
You must send video_url (a media.sume.com artifact or asset of this
workspace), start (seconds, ≥ 0), and only one of end or
duration. The API does not fetch from the open internet. First, import
the clip (POST /v1/media-imports). You must send Idempotency-Key.
Optional fields: precision, audio, output (exact only), and the usual
mode / webhook_url / wait_timeout_seconds communication fields.
The default mode is async (readCommunicationOptions). To wait a
maximum of 30 seconds for a 200 with the completed job, send
mode: "sync". If the job does not complete in that time, you get 202,
and then you poll the job.
If the submit is successful, the API returns a job (request_id is the
job ID). When the status is result_ready, GET /v1/jobs/:id/result
returns kind: video_trim. The result contains video_url (a new artf_,
never the source), duration_seconds, actual_start_seconds, precision,
audio, output, and optional warnings[]. Put that MP4 into
timeline_create video[] with source_in 0.
Each job uses a flat number of credits. The API rate card lists the current credits. There is no provider inference. Only the worker ffmpeg runs.
Program
| Field | Effect |
|---|---|
start | In-point, in seconds from the source start. You must send it. |
end | Out-point, in seconds. Send only one of end / duration. If the value is after the end of the source, it clamps, and the result gives the warning trim_clamped_to_source. |
duration | Length of the cut, in seconds. 0.2–900. Send only one of end / duration. |
precision | exact (default): frame-accurate re-encode (libx264, yuv420p). keyframe: stream copy. The cut can start a GOP early. Re-base your times against actual_start_seconds. |
audio | keep (default) or drop. Exact precision remuxes the kept audio as AAC. |
output | Optional { width, height, fps } conform for the output. exact only. Width/height 256–2160. fps 24 | 25 | 30 | 60. If you do not send it, the output keeps the source values. |
Limits (from packages/api-contract/src/index.ts): source ≤ 1800 s,
output ≤ 900 s, and output ≥ 0.2 s.
Refusals (stable codes)
| Code | When |
|---|---|
video_trim_range_required | The request has no end and no duration. |
video_trim_range_conflict | The request has end and duration together. |
video_trim_range_empty | end ≤ start, or the range is longer than 900 s. |
video_trim_output_requires_exact | The request has output with precision: "keyframe". |
ffmpeg_fields_rejected | The client sent vf / filter / ffmpeg / cmd / codec / crf / related fields. The server compiles ffmpeg. |
unsupported_media_source | video_url is not on the Sume media host. |
source_not_found | The media.sume.com URL is dead or is not from this workspace. |
unsupported_media_type | The HEAD result is not a video. |
source_duration_exceeded | The source is longer than 1800 s (worker). |
The API rejects off-host URLs (https://example.com/…) at admit. Import the
clip first.
Not this surface
| Need | Use |
|---|---|
| Probe / stills / optional STT | Video inspect |
| Audio track as a durable wav / mp3 | Audio detach |
| Put several clips in a sequence | Timeline 1.0 |
| Pixel pass (dim / crop) | Video filter |
The accurate frame at t, at the source size | Video frames |