Media tools

Video trim

Cut a [start, end) range out of one Sume-hosted clip into a new MP4. Material preparation, not timeline placement.

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).

text

POST /v1/video-trim
POST /v1/models/sume/video-trim-1.0/runs   # same body, no extra `model` field

There is no GET /v1/video-trim/:id. Poll the job envelope:

text

GET /v1/jobs/:id/status
GET /v1/jobs/:id/result

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.

bash

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
  }'

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

Media tools

Video trim

Cut a [start, end) range out of one Sume-hosted clip into a new MP4. Material preparation, not timeline placement.

text

POST /v1/video-trim
POST /v1/models/sume/video-trim-1.0/runs   # same body, no extra `model` field

There is no GET /v1/video-trim/:id. Poll the job envelope:

text

GET /v1/jobs/:id/status
GET /v1/jobs/:id/result

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

Optional fields: precision, audio, output (exact only), and the usual mode / webhook_url / wait_timeout_seconds communication fields.

bash

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
  }'

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