Hook, demo, CTA: assemble a product ad from 3 clips in one render

A short product ad is usually three beats: a hook, a demo and a call to action. Make each as its own clip, so you can swap only the hook for a test, then join them with POST /v1/timeline-1.0/render. One audio spine sets the length, video[] lists the clips in order with their start times, and a fade between slots smooths each cut. It costs $0.10 per output minute, rounded up, and the plan call is free.

What goes in the document?

What does the request look like?

Three slots on a 15-second spine: a hook from 0 to 3 s, the demo from 3 to 12 s and the call-to-action card from 12 to 15 s. Declared starts are authoritative, so check that each start equals the previous start plus its duration. A video slot can trail the spine by at most 0.5 seconds.

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: hdc-ad-001" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/voice.wav", "duration_seconds": 15 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/hook.mp4", "start": 0, "duration": 3 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/demo.mp4", "start": 3, "duration": 9,
        "transition": { "type": "fade", "duration": 0.25 } },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/cta.png", "start": 12, "duration": 3,
        "transition": { "type": "fade", "duration": 0.25 } }
    ]
  }'

How do I swap only the hook?

Keep the demo and call-to-action URLs fixed and change video[0].source_url. Each render is a separate job with its own Idempotency-Key, so give each variant a different key such as hdc-ad-001-hookB. The same key with the same body returns the original job and does not charge again.

When do I add captions?

Add them last. POST /v1/video-captions runs on a finished video up to 60 seconds and costs $0.20 per job, so run it on the winner and not on every draft. Captions on a video without speech fail with caption_no_speech.

What are the limits?

• The timeline joins; it does not generate. The three clips come from your own footage, a Format run or the video router.
• A still is a static hold, and a motion setting on a still is ignored with a motion_ignored warning.
• A source shorter than its slot is padded or looped with a soft warning, not a failure, so read warnings[] in the result.
• All URLs must be in your workspace on media.sume.com.
• POST /v1/timeline-1.0/plan returns the estimated cost and segment count without creating a job; it cannot predict pad or loop warnings.