Image slideshow video API: turn Sume images into an MP4 with music

To make an image slideshow video with the Sume API, send a Timeline 1.0 render (POST /v1/timeline-1.0/render) whose video[] slots are Sume-hosted stills, each held on screen for its slot's duration. Set audio.mode: "silence" to declare the length without a voice file, and add the music as a soundtrack.

The facts below come from the Timeline 1.0 docs and the field descriptions in the Sume API reference, read on 2026-09-26. Anything described as current behavior is read from Sume's code. For timelines with a voice and video clips, see How to assemble a long-form video.

Where do the images and music come from?

Every URL must already be your workspace's media.sume.com artifact or asset, such as the output of an earlier Sume job; an off-host URL is refused with unsupported_media_source. Images generated with POST /v1/images come back as Sume-hosted media.sume.com URLs; see image generation with reference images.

The music can be a Music Router track, read from the result artifact whose type is audio.

How do I build the slideshow request?

Give each photo a slot whose duration is how long it stays on screen, and set audio.duration_seconds (1–1800) to the total, so the last slot ends there. The API reference lists silence plus a soundtrack as the way to make a BGM-only (music-only) slideshow.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: timeline-slideshow-001" \
  -d '{
    "audio": { "mode": "silence", "duration_seconds": 12 },
    "soundtrack": {
      "url": "https://media.sume.com/artifacts/artf_demo/music.mp3",
      "gain_db": 0,
      "loop": true,
      "fade_out_seconds": 2
    },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/photo-1.png", "start": 0, "duration": 4, "fit": "blur" },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/photo-2.png", "start": 4, "duration": 4, "fit": "blur",
        "transition": { "type": "fade", "duration": 0.5 } },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/photo-3.png", "start": 8, "duration": 4, "fit": "blur",
        "transition": { "type": "fade", "duration": 0.5 } }
    ]
  }'

Which fields matter for a slideshow?

With silence, the soundtrack is the whole audio track. It still defaults to −16 dB, so the API reference says to set gain_db to 0 unless you want it quiet. Crossfades and wipes between photos work as in the video transitions guide.

Can the photos zoom or pan?

No. Stills are static holds. motion is deprecated: it is accepted and ignored with a motion_ignored warning, because Timeline combines and splits media rather than animating it. In the current code a source_in on a still is ignored too, with still_source_in_ignored.

A still is looped into its slot, so in the current code it never runs short and a transition into a photo is not downgraded to a hard cut. For real movement, Sume's model docs route product motion through image generation, then video generation, as in image-to-video; those clips go into video[] like any other.

How do I mix portrait and landscape photos?

Set fit per slot. In the current code, cover scales the photo to fill the frame and crops the overflow, contain fits the whole photo and pads with black, and stretch scales to the exact frame without keeping the aspect ratio. The API reference says blur pads a mismatched aspect ratio with a blurred copy of the frame instead of black bars.

What does a slideshow cost, and what are the limits?

The render's public rate is $0.10 per output minute on API pricing, and the reserve is ceil(audio.duration_seconds / 60) minutes.

• 1–200 slots per render, each at least 0.2 s, and 1–1800 s of output.
• duck_db needs a voice spine. With silence it is refused with duck_requires_audio_spine.
• Without loop, a soundtrack shorter than the output stops partway and the render warns soundtrack_shorter_than_spine.