compose 400: stack keys and overlay keys mixed in one layout

compose_stack_takes_no_overlay_layout and compose_overlay_takes_no_stack_layout mean the layout object in a POST /v1/timeline-1.0/compose request mixes vocabularies. A stack takes split, image_region and ratio. An overlay takes position, width_ratio and margin_ratio. Remove the keys of the other operation, or change operation to match the layout.

Compose is the Sume route that puts one still and one video into a single vertical frame, for example a product plate above a talking clip. YouTube describes Shorts as vertical video up to 3 minutes (YouTube Help, read 2026-10-05), and the default compose output is already 1080 by 1920.

Which keys belong to which operation

The field that selects the operation is operation, not mode; mode is the async or sync communication option. The timeline compose docs list the layout vocabulary:

Two valid bodies

The stack body below is the half-banner: a still on top and the video below. The overlay body would instead keep the video full frame and place the still as a plate near the bottom. Pick one, then send only its keys. Both URLs must already be your own media.sume.com artifacts, and an Idempotency-Key header is required.

{
  "operation": "overlay",
  "image": { "url": "https://media.sume.com/artifacts/artf_demo/plate.png" },
  "video": { "url": "https://media.sume.com/artifacts/artf_demo/talk.mp4" },
  "layout": { "position": "bottom", "width_ratio": 0.8, "margin_ratio": 0.12 },
  "output": { "width": 1080, "height": 1920 }
}

Finding the stray key

Mixed bodies usually come from a template that sets every layout key as a default and then switches only operation. If the template has ratio: 0.5 baked in and someone changes the operation to overlay, the refusal fires. A reliable pattern is to hold two small layout dictionaries, one per operation, and pick one by name, so a key from the wrong vocabulary can never be present. Pick the layout by name at the last step before the request is serialised.

Related wrong-axis error

A stack with the wrong region for its split is a different code: compose_image_region_wrong_axis, for left or right on a horizontal split, or top or bottom on a vertical split. The defaults, a horizontal split with the still on top and a ratio of 0.5, need no layout keys at all.

Limits and a design note

Compose output is at most 300 seconds and costs $0.02 flat per job, with the rate to be confirmed in GET /v1/catalog. The still stays on screen for the whole clip and never makes it longer. Output length always comes from the video layer. Sume does not know where a platform draws its own buttons and captions, so the margin_ratio you pick is a layout choice that you should check on a real device, not a verified safe zone.