Put a product shot above a UGC creator clip: compose stack

To show a product packshot above a creator clip in one vertical frame, call POST /v1/timeline-1.0/compose with operation: "stack", one still in image.url and one video in video.url. Set layout.ratio to the still's share of the frame, between 0.1 and 0.9, and the video takes the remainder. The result is one MP4, and the public rate is $0.02 flat per job, to be confirmed live in GET /v1/catalog.

This follows Sume's Timeline compose page, read on 2026-10-02. Compose builds one shot, so a longer ad is assembled afterwards in Timeline 1.0.

What does the request need?

The docs list these fields for a compose request.

How long is the result?

The length always comes from the video layer: video.duration, or the rest of the file from video.source_in. The still is held for the whole clip and can never lengthen it. The ceiling is 300 seconds. If video.duration runs past the source, it clamps and returns the warning compose_duration_clamped_to_source; the job still succeeds.

What about audio and a request example?

Audio passes through from the video. A mute video returns the warning compose_video_has_no_audio and still renders. The sample below puts the product 35 percent from the top, with the creator clip filling the rest, at 720 by 1280. Both URLs are placeholders.

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: ugc-product-over-creator-001" \
  -d '{
    "operation": "stack",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/product.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/creator.mp4" },
    "layout": { "split": "horizontal", "image_region": "top", "ratio": 0.35 },
    "output": { "width": 720, "height": 1280 }
  }'

When should I use overlay instead?

Use operation: "overlay" when the still should sit on the video rather than share the frame: it takes position (top, center or bottom), width_ratio (0.05 to 1) and margin_ratio, and mixing stack and overlay layout keys is a 400. The still must probe as a still (compose_image_not_still), and the video as a video (compose_video_not_video). Poll the job with GET /v1/jobs/{id}/status; there is no compose-specific GET.