URL or QR code in an AI avatar video: say it, caption it, or link it

Do not rely on an avatar video to carry a scannable QR code or a long link. The docs describe three inputs that shape the picture (an avatar, an optional product image and an optional scene reference), and none of them is documented as a placement tool for overlay graphics. The reliable paths are: say a short phrase, burn authored text with caption cues, or put the link in the text around the video.

Option 1: say it

A short branded phrase works spoken ('search our name plus demo'). A URL read aloud is slow and error-prone. If you use inline captions on the avatar job, the burned text follows the spoken script, so whatever the voice says appears on screen as the transcript says it. Check the finished transcript against your script before you publish.

Option 2: authored caption cues

The standalone Video captions endpoint accepts cues (or segments): each is text, start and end in seconds. Sume burns exactly that text at those times, with no speech-to-text. The docs describe this as the path for silent clips, and it also works for any overlay line. Only one of script_text, words, cues and segments can be sent in a request.

curl -X POST https://api.sume.com/v1/video-captions \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: url-cue-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/example/clean.mp4",
    "style": "slam",
    "cues": [{"text": "example.com/demo", "start": 24, "end": 29}]
  }'

Option 3: put the link next to the video

The most reliable place for a URL or a QR code is the page, email or post caption that hosts the clip. Viewers can tap it. A scannable code on a phone screen is also hard to scan from the same phone.

Cost and limits

A standalone caption job is a flat 0.20 dollars for videos up to 60 seconds, per the docs. If you restyle an existing caption job, send its source_caption_id; the price does not change because a restyle is still a render. Inline avatar captions are an add-on inside the avatar-video estimate and do not create a caption resource, but they do not take design overrides, so use the standalone route when you need to move the line.

Which should you pick

For a 20-second clip with one link: put it in the page text, say the brand phrase aloud, and add a cue only if you must show it on frame.

A decision rule

Ask what the viewer will do after the clip. If they will tap, put the link in the post or page. If they will search, say the brand name plus the one word they should type. If they will read a code number, use a caption cue that stays on screen for at least the length of the spoken line. Test the result on a real phone at arm's length: if you cannot read it, the viewer cannot either.

Also keep captions out of the way of platform interface elements. The standalone caption design.placement field sets where the centre of the line sits as a fraction of the frame height, which lets you lift a URL clear of the bottom controls.

Common mistakes

Spelling out a long address aloud, so the captions fill with letters. Relying on the product image to show a code, which the docs do not describe as a layout tool. Forgetting that inline captions follow the speech and not your intended overlay. Sending both script_text and cues in one captions request, which is not allowed. Ending the clip at the exact moment the cue appears, so the viewer has no time to read it.