Add captions to a long video by API: split, caption, rejoin

To add captions to a video longer than 60 seconds with the Sume API, cut it into chunks under 60 seconds with POST /v1/video-trim, caption each chunk with POST /v1/video-captions, then rejoin the captioned chunks in one POST /v1/timeline-1.0/render over the original audio from POST /v1/audio-detach. In current code, one caption job refuses a source longer than 60 seconds.

The steps come from Sume's Video captions, Video trim, Audio detach, Timeline 1.0, and Video inspect docs and the caption schema in the Sume API reference, read on 2026-09-27. Anything described as current behavior is read from Sume's code. For one clip of 60 seconds or less, see How to burn captions onto a video.

Why can't one caption job cover the whole video?

Three limits meet at 60 seconds, so a longer video needs one caption job per chunk:

• The captions docs price a standalone job for videos up to 60 seconds, under the current fixed estimate.
• The API reference caps every words and cues time at 60 seconds.
• Today the caption worker refuses a source longer than 60 seconds with duration_out_of_range, even when you pass your own words.

Where should I cut the video?

At sentence boundaries, so no caption line spans two chunks, and with no gaps, so the chunks tile the whole video. Transcribe it once with POST /v1/video-inspect, transcribe: true, and segmentation: { "mode": "sentence" } for gapless sentence segments[] with start and end in seconds. Group whole sentences into chunks under 60 seconds, start the first chunk at 0, and run the last one to the end of the video. Split a long video into short clips covers the transcript request.

• The video must already be in your workspace on media.sume.com, such as an earlier Sume job's output. Inspect, trim, and detach read sources up to 1,800 seconds.
• The transcript bills at the STT 1.0 rate, $0.01 per audio minute; the duration_seconds hint that sizes its reservation tops out at 600 seconds. The probe is unbilled.

How do I cut and caption each chunk?

Cut each chunk with POST /v1/video-trim (video_url, start, end) and keep two defaults: precision: "exact", a frame-accurate re-encode, so each seam lands where the transcript put it, and audio: "keep", because speech-to-text captions need the speech. The result's video_url is a new media.sume.com MP4.

Send that video_url to POST /v1/video-captions, which takes a public HTTPS video; the docs' own example uses a media.sume.com URL. Name the same style on every chunk so the look matches across seams. To skip a second speech-to-text, pass the chunk's words as words: rename word to text and subtract the trim result's actual_start_seconds from each time.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: talk-captions-part-2" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk-part-2.mp4",
    "style": "slam",
    "words": [
      { "text": "Next,", "start": 0.5, "end": 0.9 },
      { "text": "open", "start": 0.9, "end": 1.2 }
    ]
  }'

How do I join the captioned chunks back together?

Detach the original video's audio with POST /v1/audio-detach. Its default output is a sample-exact wav, the format Timeline's audio.url expects, and the result reports audio_url and duration_seconds. Skip the inspect transcript's audio_url: the API reference calls that 16 kHz mono file speech-to-text input, not a timeline spine. One detach outputs up to 900 seconds, so a longer source needs two range detaches, passed as audio.parts[].

Then render. Give each caption job's video_url, a captioned MP4 on media.sume.com, one video[] slot at the chunk's original start, with the chunk's length as duration and source_in 0; the trim docs place a trimmed MP4 the same way. Leave out transition, and set output.width and output.height to the source's size, because the default output is 1080×1920. In the current compiler the render's sound is the spine alone, so the original track plays once, unbroken. Check the body first with the unbilled POST /v1/timeline-1.0/plan.

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: talk-captioned-001" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/talk.wav", "duration_seconds": 150 },
    "output": { "width": 1920, "height": 1080 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/part-1-captioned.mp4", "start": 0, "duration": 58.4, "source_in": 0 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/part-2-captioned.mp4", "start": 58.4, "duration": 55.1, "source_in": 0 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/part-3-captioned.mp4", "start": 113.5, "duration": 36.5, "source_in": 0 }
    ]
  }'

What does it cost, and what are the limits?

Every step is its own job, billed on its own, plus a 5.5% agent fee by default. In the current code each trim, caption, detach, and render job takes a generation concurrency slot. For the Free plan the admission docs list one processing job and five queued by default, and a submit past the queue fails with 429 queue_full. See Video job concurrency and queueing.