Just-listed banner above 25 property clips: 25 compose jobs, $0.50

Timeline compose puts one still and one video on screen at once and returns one MP4 shot for $0.02. A just-listed banner above a property clip is operation: "stack" with the banner as image and the walkthrough as video. For 25 listings, that is 25 jobs and 25 x $0.02 = $0.50, before any Timeline render that assembles the shots.

The request

Required fields are operation (stack or overlay), image.url, and video.url. Both URLs must already be media.sume.com files of your workspace, so import the banner and the clip first with POST /v1/media-imports. The image must probe as a still (compose_image_not_still otherwise) and the video as video (compose_video_not_video). An Idempotency-Key is required.

The HTTP field that picks stack or overlay is operation, not mode. mode is the usual async, sync, or webhook communication option.

{
  "operation": "stack",
  "image": { "url": "https://media.sume.com/artifacts/artf_b1/just-listed.png" },
  "video": { "url": "https://media.sume.com/artifacts/artf_c1/walk.mp4", "duration": 12 },
  "layout": { "split": "horizontal", "image_region": "top", "ratio": 0.25 },
  "output": { "width": 1080, "height": 1920, "fps": 30 }
}

Where the length comes from

The output length always comes from the video layer: video.duration, or the rest of the file from source_in. The banner stays on screen for the whole shot and can never make it longer. The ceiling is 300 seconds. If the duration runs past the end of the source, the job clamps it and reports compose_duration_clamped_to_source, so a 12-second request on a 9-second clip gives a 9-second shot.

Cost for a batch

The rate is $0.02 flat per job, and there is no provider inference. It is worker ffmpeg only.

Fit and framing

layout.split is horizontal or vertical, and ratio is the share given to the image. image_fit takes cover, contain, or stretch. Use contain for a banner you want unclipped; cover crops it to fill its region.

Ratio is accepted from 0.1 to 0.9. Keep the banner text large and test one export before you run all 25.

Run one listing first, look at the MP4, and only then loop over the rest. The job is cheap at $0.02, but a wrong ratio repeated 25 times is still 25 wrong shots.

A loop that stays inside the rules

Send each job with its own Idempotency-Key, such as the listing id, so a retry returns the same job instead of billing twice. Use mode: "async" and collect the artf_ ids when each job succeeds, or webhook if you want a push. Rerun only the jobs that failed.

After the shots exist

Each compose returns a new artf_ video_url with its duration_seconds. Put those into Timeline video[] to build a roundup of all 25 listings, which costs $0.10 per ceil(output minute). A 25-shot roundup at 12 seconds each is 300 seconds, so 5 minutes and $0.50 in render, for $1.00 together with the compose jobs. Past 12 slots Timeline chunks the render by default, which is fine.

If you only need one listing, skip compose and send the banner as the first Timeline slot. Use compose when the banner must stay on screen while the footage plays.