Convert a landscape video to vertical 9:16 with the Sume API

To convert a landscape video to vertical with the Sume API, crop a 9:16 window out of the 16:9 clip with POST /v1/video-filter, or place the clip in a POST /v1/timeline-1.0/render slot, which outputs 1080×1920 by default, and pick a fit mode. Both read a clip already hosted on media.sume.com and return a new MP4.

The facts below come from the Video filter, Timeline 1.0, and Timeline compose docs and the Sume API reference, read on 2026-09-26. Where a behavior comes from Sume's Timeline compiler rather than the docs, it is described as the compiler works today.

Which clips can I convert?

These tools read only your own workspace's media.sume.com artifacts or assets, for example the MP4 an earlier Sume job returned. There is no open-internet fetch: an off-host URL such as https://example.com/… is rejected at admit with unsupported_media_source. Every create needs an Idempotency-Key.

If the clip is a Sume avatar video, you may not need a conversion: Avatar Video's aspect_ratio accepts 9:16, and that is its default. To generate new vertical footage instead of converting old footage, see Vertical 9:16 video generation.

How do I crop a 16:9 video to 9:16?

Use the video filter crop op. It takes the rectangle as fractions of the source frame, with x + width ≤ 1, and the compiler rounds it down to even pixels for yuv420p. The op's other ranges are in Trim, filter, or detach audio.

A full-height 9:16 window is 81/256 of a 16:9 frame's width, about 0.3164, and centering it puts x at about 0.3418. Those numbers are our own arithmetic, not a docs rule; move x between 0 and about 0.6836 to follow an off-center subject. The output is the window's own size (about 606×1080 from a 1920×1080 source, by the same arithmetic), so this request adds the allowlisted scale filter to make it 1080×1920:

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

Which Timeline fit mode should I use?

Timeline 1.0 renders a 1080×1920 MP4 by default, and output.width / output.height take other even sizes from 256 to 2160. Each video[] slot's fit decides how a 16:9 clip meets that vertical frame:

How do I render the vertical version with Timeline?

Send one slot that covers the whole output and name the fit. Today a render's sound comes from its audio spine (plus an optional soundtrack bed), not from the clips in video[], so for a clip with speech, detach its track first with POST /v1/audio-detach: its default wav is what audio.url wants. Set audio.duration_seconds (1–1800) to the clip's length.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vertical-blur-001" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
      "duration_seconds": 24
    },
    "video": [
      {
        "source_url": "https://media.sume.com/artifacts/artf_demo/landscape.mp4",
        "start": 0,
        "duration": 24,
        "fit": "blur"
      }
    ]
  }'

Can I put a banner above the landscape clip instead?

Yes, with timeline compose. POST /v1/timeline-1.0/compose with operation: "stack" tiles one still and one video in a single frame. Its default layout (horizontal, top, 0.5) puts the still on top and the video underneath, and its default output is 1080×1920. video_fit takes cover, contain, or stretch; blur is not a compose fit. The video layer's audio passes through. Timeline compose and timeline audio covers the layout keys.

What are the limits of each route?

Pick by clip length and by where the sound should come from. None of the three routes has its own GET: poll GET /v1/jobs/:id/status and GET /v1/jobs/:id/result for the new video_url.

• A source longer than 300 seconds fails the filter with output_duration_exceeded. Use a Timeline fit, or cut the clip into parts of 300 seconds or less with video trim.
• POST /v1/video-filter/check validates a crop program for free, with no job and no reserve. The filter allowlist post covers the check.
• The API pricing rate card lists a Timeline render at $0.10 per output minute, and a render reserves ceil(audio.duration_seconds / 60) minutes. The filter and compose are priced per job; GET /v1/catalog lists the live rates.