2026-10-03

Sale banner compose errors: not a still, wrong axis, clamped duration

Fix the stable Sume Timeline compose refusals for a sale banner: compose_image_not_still, compose_image_region_wrong_axis and a clamped duration warning.

5 min readSume

All posts

Which refusal is it

If a Sume compose job for a sale banner fails, read the stable code. Most come from three mistakes: the "image" is not a still, the region does not match the split, or the layout vocabulary mixes stack and overlay keys. Warnings never fail a job.

Compose takes one still and one video and returns one MP4 shot, at a flat $0.02 per job (confirm in GET /v1/catalog).

The codes

Timeline compose refusals and warnings (Sume docs)
Code	Meaning	Fix
compose_image_not_still	image.url is not a still	Send a PNG or JPEG artifact
compose_video_not_video	video.url is not a video	Send a video artifact
compose_image_region_wrong_axis	left/right on horizontal split, or top/bottom on vertical	Match region to split
compose_stack_takes_no_overlay_layout	stack job carries overlay keys	Drop position, width_ratio, margin_ratio
compose_duration_clamped_to_source	warning: video.duration ran past the file	Shorten duration or accept the clamp
unsupported_media_source	off-host URL	Import with POST /v1/media-imports first

A request that passes

curl -sS -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: fix-banner-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/sale-plate.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/product-clip.mp4", "duration": 8 },
    "layout": { "position": "bottom", "width_ratio": 0.8, "margin_ratio": 0.06 }
  }'

Read the result

Poll the job envelope at /v1/jobs/:id/status and /result; there is no compose-specific GET. A finished result is kind: timeline_compose with video_url and duration_seconds. Client-sent ffmpeg fields such as filtergraph, codec or crf are rejected with 400, because the server compiles ffmpeg itself.

Sources

Timeline compose