Video trim 400 video_trim_range_required: add end or duration

video_trim_range_required means your POST /v1/video-trim body named a start but gave the API no way to find the out-point. Add exactly one of end (an out-point in seconds) or duration (a length in seconds), and resend with a new Idempotency-Key. The error is a request-shape refusal, so nothing was queued and nothing was billed.

Sume's video trim cuts a [start, end) range out of one clip that already lives on media.sume.com and returns a new MP4. The source file is never changed, and the public rate in the docs is $0.02 per job.

Why does the trim API ask for end or duration?

A range needs two ends. The docs require video_url, start (seconds, 0 or more) and only one of end or duration. Sending neither gives video_trim_range_required. Sending both gives video_trim_range_conflict, because the two could disagree. Sending an end that is not after start gives video_trim_range_empty.

The refusal is stable, so a script can branch on the code instead of parsing the message.

What does a valid request look like?

Import the clip first, because the API does not fetch from the open internet. Then send the trim with a duration (or an end, not both).

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-hook-002" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "start": 2,
    "duration": 8
  }'

Should I send end or duration?

Use end when your notes are timestamps from a player, such as a hook that runs from 12.0 to 19.5 seconds. Use duration when the length is the rule, such as an 8 second cutdown for an ad slot. Both produce the same kind of result.

If end lands past the end of the source, the API clamps it and the result carries the warning trim_clamped_to_source. A duration below 0.2 seconds or above 900 seconds is refused, and the source itself can be at most 1800 seconds.

• Pick one of end or duration and remove the other from your template.
• Keep precision at the default exact for a frame-accurate cut. keyframe is a stream copy that can start a GOP early.
• Read actual_start_seconds in the result if you used keyframe and need to re-base other timings.
• Reuse the same Idempotency-Key only when you are retrying the identical body.

How do I read the result?

The default mode is async, so you get a job back. Poll GET /v1/jobs/:id/status, then GET /v1/jobs/:id/result, which returns kind: video_trim with a new video_url and duration_seconds. Send mode: "sync" to wait up to 30 seconds for a 200; if the job is not done in time you get a 202 and poll instead. The same flow works from the hosted MCP tool video_trim, which needs an idempotency_key.

If you hit this error from a template, check whether a missing variable made end and duration both come out as null. Drop empty fields from the body before sending.