Price badge over a 45-second clip: timeline compose overlay, $0.02

To put a price badge or logo plate over a clip with an API, call POST /v1/timeline-1.0/compose with operation: "overlay", a still in image.url, and a video in video.url. Sume returns one MP4 with both on screen. The job costs a flat $0.02, whatever the clip length, up to a 300-second ceiling.

Overlay layout fields

Compose has two operations: stack tiles the still and the video in one frame, and overlay places the still over the video. The HTTP field is operation, not mode; mode is the async or sync option. Overlay accepts these layout keys, and stack keys are refused with compose_overlay_takes_no_stack_layout.

Example: a 45-second clip

For a badge across the lower third, use position: "bottom", a width_ratio of 0.3, and the default margin. The still stays on screen for the whole clip and can never make the clip longer; the video layer sets the length through video.duration, or the rest of the file from source_in. If video.duration runs past the end of the file, the job clamps it and warns compose_duration_clamped_to_source.

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: badge-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/badge.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/clip.mp4",
               "duration": 45 },
    "layout": { "position": "bottom", "width_ratio": 0.3 }
  }'

What it costs and what it returns

The rate is $0.02 per job. It is flat because video.duration can be absent until the worker probes the file. A 45-second clip and a 300-second clip both cost $0.02. The job runs worker ffmpeg only, with no provider inference.

If you then place the shot in a timeline render, that render is billed separately: a 45-second timeline rounds up to 1 minute and costs $0.10, so the badge plus the assemble is $0.12 in total.

When the job reaches result_ready, GET /v1/jobs/:id/result returns kind: timeline_compose with a new video_url and duration_seconds.

Stack versus overlay

Use stack when the still and the video should not cover each other. The defaults, horizontal, top, and a ratio of 0.5, make the half-banner layout with the still on top and the video below. ratio is the still's share of the frame, from 0.1 to 0.9, and the video takes the exact remainder. Use overlay when the plate should float on the video, as with a price badge, a logo, or a lower-third card.

The two vocabularies do not mix. A split or ratio key on an overlay request returns compose_overlay_takes_no_stack_layout, and a position key on a stack request returns compose_stack_takes_no_overlay_layout. If the image region does not match the split axis, for example left on a horizontal split, you get compose_image_region_wrong_axis.

Constraints to know

The still must probe as a still (compose_image_not_still) and the video as a video (compose_video_not_video). Both URLs must be media in your own workspace on media.sume.com; import first with POST /v1/media-imports. Output defaults to 1080 x 1920 at the video layer's frame rate; set output.width and output.height to match the timeline you will assemble into so the shot is not rescaled twice. A mute video only warns (compose_video_has_no_audio).