Which wait to use for a 30 second clip: sync, webhook or a poll

For a 30 second video clip, use webhook mode or a poll with a deadline of about 20 minutes. Sync mode only holds the connection for up to 30 seconds, which is shorter than most video generations, and when it times out the job keeps running.

The numbers below are the documented waits, not measured generation times. Sume does not promise a completion time in the docs I read.

The documented waits

Each mode has a different clock.

Why sync mostly fits images

The /v1/images route defaults to sync with a 30 second wait and answers 200 on completion or 202 on timeout. A short image fits in that window. A video usually will not, so choose async or webhook for video and expect to poll.

A sensible combination

Submit with webhook_url and an Idempotency-Key, store the job id, and run a slow backstop poll that reads the job after a few minutes. If the webhook arrives, stop polling. If your own deadline passes, cancel only if the job has not started generating; otherwise it will complete and bill.

Handling the sync timeout is simple: it is a normal 2xx. Read the job id from it and move to polling.

The mode names can mislead. In the docs, sync and subscribe are the same bounded wait, and sending a webhook_url or callback_url without choosing a mode implies webhook. Async is the default when you choose nothing, and it returns right away with the job id for you to poll. Whichever you pick, store the job id the moment it comes back. For capacity, the submit response includes generation_limits, and a full queue answers 429 queue_full, which is safe to retry with the same Idempotency-Key after a pause.

Tradeoffs

Webhooks need a public HTTPS endpoint on the default port. Polling needs nothing inbound but costs reads. Sync is the simplest code and the least suited to long jobs.