Timeline 1.0 warnings after stitching shots: which need a fix

A Timeline 1.0 render that finishes with warnings[] has still succeeded. The docs call padded or looped short sources, snapped transitions and ignored still motion soft warnings, not failures, and the MCP tool description lists a fuller set of codes as soft degradations. So the answer to "do I re-render?" is usually no, with a few exceptions you can spot by reading the codes.

This is a reference for the codes you meet when you stitch AI-generated shots together. Where the docs explain a code, I say what it means. Where they only list the name, I say that too rather than guess.

Where do the warnings appear?

A finished render's GET /v1/jobs/:id/result has kind: timeline_render with video_url, duration_seconds, segment_count, billable_minutes and an optional warnings[]. Over MCP, timeline_get reads the same result. The unbilled plan call (POST /v1/timeline-1.0/plan) cannot predict warnings about short sources, so the list below is for after the render, plus a few you can avoid up front.

Which codes are explained in the docs?

The two that most often deserve action on a stitched film are the fps resample and the short-source pad or loop, because both are visible. The rest are bookkeeping.

Which codes do the docs only name?

The MCP tool description lists these as soft degradations: timeline_gap_filled, video_coverage_shorter_than_audio, output_av_drift, soundtrack_shorter_than_spine, soundtrack_source_replaced, soundtrack_source_omitted and edge_fade_shortened. Their exact triggers are not spelled out in the public docs I read, so treat the names as hints.

What the docs do say can narrow it down. video[].duration coverage may trail the spine by at most 0.5 seconds, which is the territory of video_coverage_shorter_than_audio and timeline_gap_filled. The soundtrack bed has its own loop, fade_out_seconds and duck_db settings, which is where the soundtrack_* codes come from. Edge fades must not exceed the output length (edge_fades_exceed_output is the hard refusal), so edge_fade_shortened is the softer sibling. If one of these appears and the film plays correctly, the docs give no reason to re-render.

How do I read them in code?

The check below prints the warning codes and flags the three worth a second look. It reads the finished job result, so run it after jobs_wait or after polling the status route. It needs no extra credentials beyond the key you used to submit.

If you want to pre-empt the two visible ones, set output.fps explicitly to the rate your clips share (24, 25, 30 or 60) and confirm each clip's length with a probe before you declare slot durations.

import os, sys, requests

job_id = sys.argv[1]
H = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}
r = requests.get(f"https://api.sume.com/v1/jobs/{job_id}/result", headers=H)
r.raise_for_status()
res = r.json()
res = res.get("data", res)
watch = {"output_fps_resamples_sources", "segment_source_short_looped",
         "segment_source_short_padded", "audio_spine_low_fidelity"}
for w in res.get("warnings", []):
    code = w.get("code", w) if isinstance(w, dict) else w
    print(("CHECK " if code in watch else "ok    ") + str(code))
print(res.get("video_url"))

What is a failure, not a warning?

Refusals come at submit time with stable codes, and they stop the job before it renders: timeline_must_start_at_zero, segment_overlap, transition_too_long, too_many_chained_transitions (more than 8 adjacent fades; insert a hard cut), render_strategy_unsafe (single above 12 slots) and unsupported_media_source for any off-host URL. These are 400s, not warnings, so they never produce a finished video.

So the practical rule is simple. A 200 or finished job with warnings is a film you can ship; check the visible ones. A 400 with a code is a document you must fix. The unbilled plan route is the cheapest place to find the second kind.