Video frames job succeeded but one frame url is null

A video frames job can finish ready and still hold a frame with url: null. The docs say one instant whose extract failed comes back with url null, and that this does not fail the job. So a ready job is not proof that every requested instant has an image; check each entry.

Behavior is from the video frames docs, read 2026-10-01. Topaz Labs' September 2026 page, read the same day, lists upscale and restore workflows that take stills; null entries are worth filtering before you send anything on.

What does the result look like?

When resource_status is ready, frames is a list of { t, url, width, height }, with url pointing at a durable artf_ image. source_duration_seconds is what the worker probed. The failed instant keeps its t and has a null url.

How do I filter the nulls?

Read the resource, split the entries by url, and keep the failed times for a second request.

const res = await fetch("https://api.sume.com/v1/video-frames/" + id, {
  headers: { Authorization: "Bearer " + process.env.SUME_API_KEY },
});
const body = await res.json();
const frames = body.video_frames?.frames ?? body.frames ?? [];
const good = frames.filter((f) => f.url !== null);
const missing = frames.filter((f) => f.url === null).map((f) => f.t);
console.log(good.length, "ok, retry at", missing);

How do I get the missing frames?

Submit a new request with at set to the missing times and a fresh Idempotency-Key, since the body differs from the first. The docs do not state why a single instant fails, so compare t with source_duration_seconds before retrying. The call is unbilled. An at value outside the clip fails the job instead, with frame_time_out_of_range; see frame_time_out_of_range.