Free-returns ribbon across the top of a clip: compose overlay

To put a free-returns ribbon along the top of a product clip, use Sume timeline-1.0/compose with operation: "overlay" and layout.position: "top". The ribbon is a still you made yourself, the clip stays full frame behind it, and the job returns one MP4 for $0.02. The still stays on screen for the whole clip.

The overlay keys are in Timeline compose (read 2026-10-06). Make the ribbon text yourself in an image tool. Burning words in with compose is not possible, because the still is placed as given, so a price or date change means a new still.

How wide and how far from the edge?

width_ratio is the plate's width as a share of the frame width, from 0.05 to 1, with a default of 0.9. margin_ratio is the gap from the edge as a share of the frame height, from 0 to 0.45, with a default of 0.05. The plate keeps its own aspect, so a wider ratio makes a taller ribbon too.

What does the request look like?

Import the ribbon and the clip first, since both URLs must be this workspace's media.sume.com files. The ribbon must probe as a still, or the job refuses it with compose_image_not_still.

curl -X POST https://api.sume.com/v1/timeline-1.0/compose \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: returns-ribbon-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/returns-ribbon.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/scarf.mp4" },
    "layout": { "position": "top", "width_ratio": 0.9, "margin_ratio": 0.05 }
  }'

What should I check before publishing?

Check the ribbon against your own store policy, since Sume does not know your return terms, and read the result frame by frame. Keep text away from the part of the frame a platform's own buttons cover, which you can find on that platform's own help pages.

• Do not mix stack keys such as split or ratio into an overlay request.
• The clip's length decides the output length, up to a ceiling of 300 seconds.
• A mute source clip is a warning, not a failure.