How to add text over a video: timed titles and labels

To add text over a video, draw the words into the frames for the seconds you want them on screen: a title at the start, a label on a product shot, a callout at a key moment. With Sume, send the clip to POST /v1/video-captions with cues, each a text, a start, and an end in seconds. Cues skip speech-to-text, so Sume burns exactly your words at your times, and design.placement.anchor_ratio sets how high the line sits.

Sume facts come from the Video captions docs and the caption schema in the Sume API reference, read on 2026-09-27; where a detail is current code rather than docs, it says so. Captioning the speech itself is covered in how to burn captions onto a video.

How do I put text on a video at a specific time?

Give each piece of text its own cue. A cue shows from start to end, in seconds from the start of the clip, and video_url is the clip's public HTTPS URL.

Leave style out and Latin text gets slam. In current code that style draws text in capitals and lays a light black tint, at 18% opacity, over the whole frame. cues cannot be combined with words, segments, or script_text, so one job is either your text or captions of the speech.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: text-overlay-001" \
  -d '{
    "video_url": "https://example.com/product.mp4",
    "design": { "placement": { "anchor_ratio": 0.2 } },
    "cues": [
      { "text": "The travel edition", "start": 0, "end": 2.5 },
      { "text": "Folds flat, fits a carry-on", "start": 6, "end": 9 }
    ]
  }'

How do I choose where the text appears?

design.placement.anchor_ratio is the line's center as a fraction of the frame's height, from 0.05 to 0.95, for portrait frames; landscape_anchor_ratio does the same for landscape. In current code the fraction is measured down from the top, so 0.1 sits near the top and 0.9 near the bottom, and a landscape frame uses anchor_ratio when you send no landscape_anchor_ratio.

• Placement is vertical only: placement has just those two keys, and there is no horizontal position.
• One job has one design, so every cue sits at the same height. For text at a second height, run another caption job on the first job's captioned video.
• design works on every style except punch and tiktok-green. Size, color, and the enter and exit timing are other design tokens, covered in customize burned-in captions.

What are the limits?

A caption job is sized for short clips. These are the numbers to check:

Can I use the video filter, or put the text above the video?

Not with the filter: drawtext and subtitles are not on the Video filter allowlist, so it can't draw words.

For a text bar above the picture, the meme layout, the text has to be a still image. Timeline compose with operation: "stack" tiles a still and a video in one frame, still on top by default, and returns one MP4. Both files must already be on media.sume.com in your workspace, such as earlier Sume outputs; Timeline compose covers the layout keys.

How do I get the result, and what does it cost?

Poll GET /v1/jobs/:id/status, then read the new video_url from GET /v1/video-captions/:id. Each accepted caption job reserves and captures the fixed amount listed on the Video captions page, for videos up to 60 seconds; confirm live pricing in GET /v1/catalog.