Crop 16:9 to 9:16 with video filter: the fractions to send

To cut a centred 9:16 frame out of a 16:9 clip, send video filter one crop op with x 0.3418, y 0, width 0.3164 and height 1. The fractions are relative to the source frame, so they hold for any 16:9 size. On a 1920x1080 source the crop is about 607.5 pixels wide by 1080 tall, and the compiler rounds to even values. The job is $0.02 per encode and the source stays unchanged.

The result is a new MP4 with a 9:16 shape, which you can put into a Timeline video[] slot at 1080x1920. Because the crop already has the right shape, fit: cover then scales it without cutting anything further.

Where the numbers come from

A 9:16 frame at the full source height of 1080 is 1080 x 9 / 16 = 607.5 pixels wide. As a fraction of the 1920-pixel width that is 607.5 / 1920 = 0.3164. To centre it, the left edge sits at (1 - 0.3164) / 2 = 0.3418. The docs require x + width <= 1, and 0.3418 + 0.3164 = 0.6582, well inside.

To follow a subject that is not in the middle, change only x. For a subject on the left third, x 0.1 gives 0.1 + 0.3164 = 0.4164 on the right edge, still legal. The docs bound x and y to [0, 1] and width and height to [0.05, 1].

Check first, then encode

Video filter has an unbilled contract check at POST /v1/video-filter/check. It runs the schema, the op allowlist and the source check, creates no job and reserves no credit. A valid answer carries an estimate and next_action: submit_video_filter. The check needs no Idempotency-Key; the real encode does.

The source must be a media.sume.com artifact or asset of your workspace and no longer than 300 seconds. For longer footage, cut it first with video trim, which accepts a source of up to 1800 seconds.

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/wide.mp4",
    "ops": [
      { "op": "crop", "x": 0.3418, "y": 0, "width": 0.3164, "height": 1 }
    ]
  }'

curl -X POST https://api.sume.com/v1/video-filter \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crop-916-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/wide.mp4",
    "ops": [
      { "op": "crop", "x": 0.3418, "y": 0, "width": 0.3164, "height": 1 }
    ]
  }'

Crop or let Timeline do it

Timeline's fit: cover already crops to fill the frame, always from the centre. Use the filter job when you want control of the window, for example to keep a speaker who stands off-centre. Use fit: blur when you would rather keep the whole 16:9 picture on a blurred background and avoid cropping at all.

Google's help page on square and vertical video says to use those shapes to engage mobile customers, and the related post on in-between ratios covers which sizes the Google Ads page accepts. A cropped, vertical-shaped file fits that advice without changing the story of the clip.

Mistakes the API refuses

A crop outside the frame is refused with video_filter_crop_out_of_bounds, which also covers a side below 0.05. A crop op with an extra key is refused with unsupported_filter_op_field. More than eight ops is refused with video_filter_too_many_ops. Sending ffmpeg keys such as vf or codec is refused with ffmpeg_fields_rejected, because the server compiles ffmpeg itself.

Each of these shows up in the free check, so a wrong fraction costs nothing.

After the crop

Take the result's video_url, a new artifact, and put it in a Timeline video[] slot with source_in 0. The cropped file keeps the frame rate and audio of the source unless the program changes them, so a clip with its own sound still carries it; the Timeline audio spine decides what is heard in the final render.

Verify the framing with video frames on the cropped artifact: ask for one still near the start and one near the end, at the source size, and look at whether the subject stays in the window. A static crop cannot follow a moving subject, so if the person walks across the 16:9 frame, either split the clip with video trim and crop each part with its own x, or use fit: blur instead.

Two ops can be combined in one job, up to eight, applied in order before any filtergraph. A common pair is the crop followed by a dim of 0.9, which darkens the whole clip by ten percent so that burned-in text reads better. Each extra op in the same job is still one $0.02 encode.