Automatic failover versus timeout hedging for video jobs, and what each costs

Updated 2026-10-02

Video generation hosts fail in two different ways, and VideoRouter handles them with two different mechanisms. One is on by default and costs nothing. The other is opt-in, can bill you twice, and is easy to misuse. Knowing which failure each one covers is the difference between a reliable pipeline and a surprising invoice. This page explains both from VideoRouter's documentation, then gives a decision rule.

Failure type one: the submission is rejected

You send POST /videos and the chosen host refuses it: it is down, rate-limited or errors out. This happens before any job id exists. The documented default behaviour is: retry once on the same host, then walk every other host confirmed to serve that exact checkpoint, cheapest first, until one accepts the job. You do not configure anything; omit the provider field and this is what you get. A job that ends up failing because every host failed returns a 5xx and is not billed.

This covers the most common outage shape, a host that is visibly broken. It is also why a soft host preference such as model/host is not a guarantee: if that host rejects the request, the walk continues elsewhere. For a strict pin use provider.only with allow_fallbacks: false, as covered in the pinning article.

Failure type two: the job is accepted, then stalls

The host returned a job id and status queued or in_progress, and then nothing happens. No error, no completion. Automatic failover cannot help, because from the router's point of view the submission succeeded. The documentation says so directly: the default walk only covers the submission call, and a job that is already accepted and then stalls needs the opt-in hedge.

The hedge: failover.on_timeout_sec

The hedge is a separate top-level object, not part of provider:

{
  "model": "kling-v3.0-std",
  "prompt": "a paper airplane gliding over a city",
  "duration_secs": 5,
  "failover": {"on_timeout_sec": 240}
}

If the job has not finished by that deadline, VideoRouter resubmits it to the next-cheapest untried host without cancelling the original. The documentation is explicit about the cost: both attempts are billed if they land. That is the price of insurance: you are buying a second chance at a deadline by being willing to pay for two clips when the first was merely slow rather than dead.

Side by side

The cost trade-off, in plain terms

Let p be the share of jobs that run past your deadline, and c the cost of a clip. With the hedge on, expected spend is about c x (1 + p) in the worst case where every late job later completes on both hosts. So the hedge is cheap when p is small and the deadline sits well above your normal completion time. It is expensive when you set the deadline near your median, because then roughly half your jobs trigger a second submission. Measure your own completion-time distribution first; the host table below also shows how much the second host's price can differ from the first, which matters because the hedge goes to the next-cheapest untried host.

Per second, before VideoRouter's 2% platform fee. For tiered models each row compares the resolution tier with the widest host-to-host gap. Built 2026-10-02 from the live catalog.

When to enable it

• A user is waiting and a hard deadline matters. An interactive preview that is useless after four minutes is a candidate.
• Stalls, not failures, are your observed problem. If your logs show accepted jobs sitting in queued far past typical times, the hedge addresses exactly that.
• The clip is cheap relative to the cost of lateness. Short drafts on lighter models make double-billing tolerable.

When to leave it off

• Batch work with no deadline. A slow job in a queue is cheaper than a hedged one. Just keep polling.
• Expensive finals. Doubling a premium-tier clip is the worst place to be generous.
• When you already resubmit on timeout yourself. Do not combine the two. Your resubmission plus the platform hedge can produce three paid jobs for one request.

Alternatives that cost less

Before turning on the hedge, consider ordering hosts by measured performance. provider.sort accepts "latency", "reliability" and "queue", and provider.preferences can filter hosts by measured 24-hour p95 latency and success rate. These shift which host is tried first, with no double billing. Treat them as the first lever and the hedge as the second; hosts with no measured data sort last, so they behave best on models with real traffic.

Handling the outcome in code

A hedged request still gives you one job id to poll. Keep your own deadline longer than the hedge deadline plus a normal completion time, and record the provider field from the completed job so you can see how often the hedge actually fires. If it fires often, your deadline is too tight or a host has a real problem; fix that rather than paying for it indefinitely. The surrounding retry rules are in the error cookbook, and the provider selection docs hold the full field list. To try it, create a key and cap it first.

Frequently asked questions

Keep reading

• Async Video Jobs Explained — Polling, Timeouts and Retries
• Video API Authentication and Spend Controls: Keys, Caps, Limits
• Video API Error Handling Cookbook: Retries, Backoff, Duplicates
• Production Video Generation Pipeline: Queue, Workers, Python