Which Sume wait mode fits which job: image, video, avatar, swap

Use async or webhook for anything that can run longer than 30 seconds, which in practice means video, avatar video and face swap. Use sync only when a short job usually finishes inside the wait, and never treat its timeout as a failure. The mode decides how you learn the outcome. It never changes whether a job is created, what it costs, or how long it runs.

Every mode returns the job id in its first response, because Sume answers once it has a durable job. A 2xx means that paid work is in flight, not that it finished. Read terminal and result_ready from the envelope.

30 seconds is a wait budget

The API clamps wait_timeout_seconds to 0-30. That limits how long the HTTP request blocks, not how long the job takes. Image jobs often finish in the budget. Video, avatar-video and face-swap jobs usually do not.

When the budget ends, or when the API process has no waiter capacity, the response is still 2xx with the job id and the poll URLs. sync.timed_out or sync.capacity_exhausted tells you which. Then you must continue with GET status_url, obey next_poll_after_seconds when present, and never submit a new paid job for the same intent. You may retry the submit itself with the same Idempotency-Key.

Choosing in practice

If you omit mode, you get async. If you send webhook_url or callback_url without a mode, you get webhook. A sync or subscribe response is not an event stream: the Developer API has no SSE or WebSocket transport, and GET /v1/jobs/{id}/events is a pull snapshot.

• Stills, short audio: sync is acceptable, with a poll fallback in the client.
• Clips and anything with minutes of runtime: async plus a poll loop, or webhook plus a slow poll.
• Progress bars: poll events, because subscribe sends none.
• Webhooks deliver only job.completed, job.failed and job.canceled.

The TypeScript equivalent

For a long wait in your own client, the docs name the pattern 'client subscribe': submit with async, loop on status, then read the result. In TypeScript, waitForJob from @sume-com/sdk is that loop, with a 20-minute default timeout and a 2-second floor on the poll interval. A timeout there stops your wait only; the job keeps running and billing.

Common mistakes

Setting wait_timeout_seconds to a large value does not give a longer wait; the API clamps it to 30. Treating a sync.timed_out response as a failure leads to resubmits and double billing. Expecting subscribe to stream progress leads to a progress bar that never moves.

If you send mode: "webhook" without a webhook_url, the request is invalid; the URL must be public HTTPS, and localhost and private networks are rejected. Whichever mode you pick, store status_url, result_url, events_url and cancel_url from the envelope.