Video captions take a public HTTPS URL; other media tools do not

When you chain Sume tools to make a vertical 1080x1920 file, the input rule changes at the caption step. Video captions takes a public HTTPS video_url that Sume can fetch. Video trim, video filter, video frames, video inspect and Timeline 1.0 take a media.sume.com artifact or asset that your workspace owns, and reject any other host at admit.

The lookup table

Every tool below returns a new durable file, except video frames and inspect, which return stills (and inspect also returns probe facts and optional text).

What captions refuses

The captions docs list the rejected URL kinds: localhost, private-network, non-HTTPS, signed or private URLs, and provider task URLs. A clip behind a signed bucket link therefore fails at the caption step even though it worked as input to trim. The captions docs example uses a media.sume.com/artifacts/... URL, which is the natural source when the previous step was a Sume tool, so the usual order is: trim and filter first, captions last.

A chain that respects the rules

Import once, then pass each step's result URL to the next. Put captions last so the burned text lands on the final 1080x1920 frame, and so the one caption job (fixed estimate $0.20 for clips of at most 60 seconds, confirm with GET /v1/catalog) sees the cut you will post.

Import the clip first with POST /v1/media-imports and send an Idempotency-Key on writes.

• Import: POST /v1/media-imports returns the media.sume.com URL.
• Cut: POST /v1/video-trim with start and duration.
• Crop and scale: POST /v1/video-filter, scale=1080:1920,setsar=1.
• Captions: POST /v1/video-captions with the result video_url.

Errors you can hit

The two input rules fail in different ways, so read the error before you change anything. A Sume-hosted tool given an off-host URL such as https://example.com/clip.mp4 is rejected at admit, before a job exists; the fix is to import the clip. A Sume URL from another workspace or a dead link returns source_not_found. Captions given a private or signed link is rejected for that reason, and the fix is a public HTTPS URL or a Sume artifact URL.

Captions also have their own typed errors: caption_no_speech when speech-based captions find no speech (switch to cues), script_alignment_mismatch or script_alignment_failed when script_text cannot be aligned (simplify the script or omit it), and caption_hangul_text_latin_style when Korean text is sent to a Latin style. To change only the look, send source_caption_id in place of video_url; Sume reuses the stored word timings, so speech-to-text does not run again.

A note on order

The order matters for cost as well as for URLs. Trim and filter jobs are $0.02 each, and a caption job is a fixed $0.20 estimate for clips of up to 60 seconds, so do the cheap cuts first and caption only the final cut. A restyle through source_caption_id costs the same as a first caption job, so settle the framing before you burn text.