Face swap API sync mode waits at most 30 s: then poll, do not resubmit

On Sume, a face swap submitted with mode sync or subscribe waits at most 30 seconds for a terminal state. If the job is not finished by then, you get the same job envelope back, and the docs say to poll rather than resubmit. Resubmitting a beta face swap would reserve the 15-second price again: $2.76, $3.675 or $8.25 depending on tier.

What each mode does

The face swap docs list three communication options: async (the default), sync or subscribe with wait_timeout_seconds, and webhook with a public HTTPS webhook_url. The jobs page says wait_timeout_seconds is clamped to 0 to 30, that subscribe is an alias of sync, and that neither produces progress events.

The 30-second ceiling is a property of the HTTP wait, not of the job. The job continues on Sume's side whether or not your client is still connected. That is why the docs say to poll or use a webhook for work that can last longer than 30 seconds.

What the envelope tells you

The envelope carries status_url, result_url, events_url and cancel_url, and a sync object. sync.timed_out is true when the wait returned before a terminal state, and sync.capacity_exhausted is true when Sume skipped the wait because the waiter budget was full. Treat both as 'keep polling'.

A beta swap renders a source of up to 15 seconds, so finishing inside 30 seconds should not be assumed. Use async plus polling, or a webhook, as the jobs page recommends for new integrations.

If you use the CLI or MCP rather than raw HTTP, the same rule holds: wait calls are bounded and the answer is to keep polling the same job id. Store the job id as soon as the submit returns, before any wait, so a crash does not lose the handle to a paid job.

• Readiness on the resource: resource_status.
• Progress on the job: job_status.
• Reuse the same Idempotency-Key if you must retry a submit that never returned.

A safe pattern

Submit with async and an Idempotency-Key. Poll GET /v1/jobs/:id/status until terminal is true, then read GET /v1/jobs/:id/result when result_ready is true. A completed swap exposes a public video_url under media.sume.com. If your client times out on the submit itself, repeat the call with the same key rather than a new one, so you do not pay for two swaps.

The webhook option removes the polling loop altogether. Send a public HTTPS webhook_url with the submit, and Sume calls it when the job reaches a terminal state, as described on the webhooks page. Your handler should verify the signature with a non-empty secret, refuse anything else, and then read the result from the job. Combined with the Idempotency-Key on the submit, that gives you one paid swap per source clip and no wasted waiting.