Before-and-after video generator API: build the reveal

To make a before-and-after video with the Sume API, call the catalog Format sume-before-after with your real before and after photos in attachments. Two other paths use the same pair: generate the change with POST /v1/videos, the before photo as first_frame and the after photo as last_frame, or, once both images are Sume-hosted, wipe from one to the other in a Timeline 1.0 render, with nothing generated.

Facts come from the Format catalog, Format API, Create a run, Video generation, and Timeline 1.0 docs pages and the Format's published description, read on 2026-09-27. The frame fields themselves are covered in Image-to-video API: set the first and last frame.

Which way should I build the reveal?

The Format makes the production choices for you, the frame path leaves the motion to a model and your prompt, and the Timeline wipe only assembles the two images you give it.

What does the before-and-after Format make?

sume-before-after makes “a finished before-and-after transformation video with matched identity, framing, lighting, and a clear reveal”. Its description names “beauty routines, styling changes, cleaning demos, fitness presentation, and product transformations backed by supplied evidence” and ends “Not for: static campaign deliverables”. The evidence is yours to supply: send photos of the real before and after, and treat “matched identity” and the rest of that wording as the Format's aim, not a guarantee.

Call it with a key that has formats:write. Label each photo with filename, the label the agent sees, and say in instruction which is which; your instruction wins where it disagrees with the recipe.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-before-after/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kitchen-reveal-v1" \
  -d '{
    "instruction": "Reveal video: before.jpg is the kitchen before cleaning, after.jpg is after.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/before.jpg", "filename": "before.jpg" },
      { "type": "input_image", "image_url": "https://example.com/after.jpg", "filename": "after.jpg" }
    ],
    "generation_spend_cap_usd": 20
  }'

How do I generate the change between two photos?

Send both photos in frame_images on POST /v1/videos: the before photo with frame_type: "first_frame" and the after photo with "last_frame". The model generates the motion between them from your prompt, so treat the middle of the clip as an illustration, not a record. Only a model whose supported_frame_images lists last_frame takes the second photo; the docs' seedance-2 entry lists both, and GET /v1/videos/models shows the rest.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kitchen-both-ends-v1" \
  -d '{
    "model": "seedance-2",
    "prompt": "One continuous shot as the cluttered kitchen becomes clean",
    "duration": 5,
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/before.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/after.jpg" }, "frame_type": "last_frame" }
    ]
  }'

How do I make a wipe reveal without generating anything?

Timeline 1.0 assembles media with ffmpeg only, with no provider inference. Put the two images in video[] as stills, which are static holds, and give the second slot a wipeleft or wiperight transition. With no voice track, audio.mode: "silence" declares the length.

• Every URL must already be your workspace's media.sume.com artifact or asset, such as the output of an earlier Sume job; off-host URLs are rejected at admit. The docs say upload helpers are not the default public API path, so this path fits images Sume already hosts.
• A transition goes on a slot after the first and lasts at most 1 second and at most 50% of the shorter neighboring slot. More rules are in Video transitions API.
• POST /v1/timeline-1.0/plan checks the document without creating a job, reserving credits, or downloading media; see Validate a timeline before rendering.
• The default output is a 1080×1920 MP4.

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: kitchen-wipe-v1" \
  -d '{
    "audio": { "mode": "silence", "duration_seconds": 6 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/before.png", "start": 0, "duration": 3 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/after.png", "start": 3, "duration": 3,
        "transition": { "type": "wipeleft", "duration": 0.8 } }
    ]
  }'

What are the limits of each path?

From the same pages:

• Format: attachments are JPEG, PNG, WebP, GIF, or AVIF, up to 30 images, 30 MB each and 500 MB per run. An API run is unattended, and a run that cannot finish comes back failed, never a half-finished completed.
• Both ends: frame URLs must be public HTTPS. If a request also carries input_references, frame_images takes precedence.
• Timeline: 1–200 slots, each at least 0.2 seconds, and 1–1800 seconds of output. A transition on the first slot is refused with transition_on_first_segment. The reserve is ceil(audio.duration_seconds / 60) minutes, so a short reveal reserves one.