AI video generation API progress updates without a push stream

To show progress for a long Sume video job, poll what the API publishes: GET /v1/jobs/{id}/events for a generation job's lifecycle timeline, GET /v1/format-runs/{run_id}/events for a Format run's phase timeline, and scene_previews for an avatar video's scenes. There is no SSE or WebSocket stream, and Sume exposes no per-job ETA.

The details come from Sume's Jobs and results, Runs and results, and Waiting for runs and jobs docs and the Sume API reference, read on 2026-09-26.

Is there a streaming progress API?

No. The Developer API has no SSE or WebSocket transport today, and GET /v1/jobs/:id/events is a pull snapshot, not a stream. Format runs have no push channel for progress either: completion is what the webhook pushes.

• mode: "subscribe" is an alias of sync: one wait of at most 30 seconds, with no progress events.
• Job webhooks are terminal-only: job.completed, job.failed, and job.canceled. There are no progress or partial webhooks.
• Agent Completions: streaming is not available yet.

What can a generation job show while it runs?

Poll the job's events_url, GET /v1/jobs/{id}/events. It returns a sanitized lifecycle timeline. Each event carries a type, a source (sume or webhook), a status (info, pending, processing, succeeded, failed, canceled, or retrying), a message, and created_at. Raw provider task ids and provider URLs are left out.

What does the status payload add?

GET /v1/jobs/{id}/status carries the fields a progress view branches on. The polling loop itself is in how to poll an AI video job's status.

• terminal and result_ready: stop polling on the first, and read result_url once the second is true.
• next_poll_after_seconds: the suggested minimum delay before the next poll, null once terminal.
• queue.state: waiting, deferred, runtime_unavailable, processing, completed, failed, or canceled, with a provider-neutral reason and available_at, the earliest time the job is eligible for pickup or retry.
• queue.position: null until Sume computes a real queue rank. The API does not return fake positions.
• logs_available: false. Lifecycle diagnostics come through events_url instead of inline logs.
• next_action: inspect_events on a failed or canceled job, so a failure view can show the events timeline.

How do I show a Format run's progress?

Read the receipt's events_url, GET /v1/format-runs/{run_id}/events. It lists phases oldest first (preparing, running, finalizing), each with at, a status, and duration_ms when the phase measured itself. Agent output, tool calls, and sandbox internals are not published there. If the last entry's at stops advancing for several minutes, the run is stalled, not slow; how long AI video generation takes covers what follows.

In TypeScript, timeline: true hands the timeline to onStatus as snapshot.timeline, and getFormatRunTimeline reads it for a run you are not waiting on. The option doubles the wait's request rate, and a failed timeline read keeps the previous timeline instead of ending the wait. Action and Agent Completion runs report events_url: null.

import { createSumeClient, subscribeFormatRun } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });

const run = await subscribeFormatRun({
  client,
  path: { handle: "acme", slug: "product-promo" },
  body: { input: { product_url: "https://example.com/p/123" } },
  timeline: true,
  onStatus: (status, snapshot) => {
    const phase = snapshot.timeline?.at(-1);
    console.log(status, phase?.phase, phase?.status);
  },
});

How do I show scene previews on an avatar video?

Avatar Video jobs carry scene_previews on the job record from GET /v1/jobs/{id}. The API reference describes it as public-safe Avatar Video scene preview metadata for status polling, with prompt text, dialogue, and provider details left out. Each entry has an index, a status (queued, processing, ready, failed, or canceled), and a preview_image_url for that scene's first frame when available. It can also carry your scene id from video_inputs[], plus start_time_seconds, end_time_seconds, and duration_seconds.

A suggested UI: show each scene's status, and its still once preview_image_url is set. Preview stills are never captioned. To approve stills before paying for the full render, use avatar video previews.

What should a progress UI not promise?

Keep the UI to what the API reports:

• An ETA or a queue position. Sume exposes queue counts and remaining accepted capacity, not a per-job queue position or ETA.
• Logs or agent output. Job events are sanitized, and the Format timeline is not a log stream.
• Mid-run webhooks. Webhooks arrive at the end, so keep polling available as the backup for missed deliveries.
• Phases for Action or Agent Completion runs. They have status, not a timeline.
• Second-by-second updates. The runs docs say polling every second buys nothing and spends read budget. Reads have their own per-minute budget, forty times the write number, so polling cannot starve your creates, but timeline: true still doubles the reads.