Timeline compose overlay on 1080x1920: a 972 px plate, 96 px margin

With Sume Timeline compose in overlay mode on the default 1080x1920 output, the default plate is 972 pixels wide (0.9 x 1080) and sits 96 pixels from its edge (0.05 x 1920). The job costs $0.02 flat. Both numbers are ratios, so they scale if you change output.width and output.height.

Compose takes exactly one still and one video from your workspace's media.sume.com and returns one MP4, as the timeline compose docs describe. The still stays on screen for the whole clip, and the output length comes from the video layer.

Overlay ratios turned into pixels

width_ratio is 0.05 to 1 of the frame width, with a default of 0.9, and the plate keeps its aspect. margin_ratio is 0 to 0.45 of the frame height, with a default of 0.05. position is top, center or bottom.

Stack mode on the same frame

stack tiles the still and the video in one frame. The defaults are split: horizontal, image_region: top and ratio: 0.5, where ratio is the still's share (0.1 to 0.9) and the video takes the remainder. On 1920 pixels of height, ratio 0.5 gives a 960-pixel still and a 960-pixel video; ratio 0.25 gives 480 and 1440.

Do not mix the vocabularies. split, image_region and ratio belong to stack; position, width_ratio and margin_ratio belong to overlay. A mix returns a 400 with compose_stack_takes_no_overlay_layout or compose_overlay_takes_no_stack_layout.

{
  "operation": "overlay",
  "image": { "url": "https://media.sume.com/artifacts/artf_demo/label.png" },
  "video": { "url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "duration": 12 },
  "layout": { "position": "top", "width_ratio": 0.9, "margin_ratio": 0.05 }
}

Things to know before submitting

Import both files first with POST /v1/media-imports; off-host URLs are rejected. Idempotency-Key is required. The ceiling is 300 seconds of output, and a duration past the end of the file is clamped with compose_duration_clamped_to_source. A mute video warns with compose_video_has_no_audio and still renders.

• 1,000 labelled clips: 1,000 x $0.02 = $20.00.
• A different output size than the timeline you plan to join causes a second rescale, so set output.width and output.height to match.
• An explicit output.fps that differs from the clip warns output_fps_resamples_sources.

Checking the result

After the job finishes, GET /v1/jobs/:id/result returns kind: timeline_compose with a new video_url and duration_seconds. Put that MP4 into a Timeline 1.0 video[] slot to assemble it with other shots and a voiceover. Inspect one still of the output to confirm the plate sits where you expect before you run a batch of hundreds.

A quick sizing test helps. On a 1080x1920 frame, the default plate of 972 pixels leaves 54 pixels on each side, since (1080 - 972) / 2 = 54. If your label or logo has built-in padding, it may look smaller than planned, so test with the real asset.