Port a fal queue submit and poll loop to Sume /v1/videos in Python

A fal queue client submits to queue.fal.run, polls a status URL and then fetches a result URL; the Sume equivalent submits to POST https://api.sume.com/v1/videos, polls the polling_url it returns and downloads from unsigned_urls[0]. The loop is about the same length. What changes is the auth scheme, the model id and the status words.

fal's steps are from its Queue page, read 2026-10-10. Sume's are from the Videos API and Jobs and results docs.

Field map

The fal page shows POST https://queue.fal.run/{model-id} with an Authorization: Key $FAL_KEY header. Status comes from GET .../requests/{id}/status, the result from GET .../requests/{id}, and a cancel from PUT .../cancel. Statuses are IN_QUEUE, IN_PROGRESS and COMPLETED. A webhook is set with webhook_url or the ?fal_webhook= query parameter.

The Sume loop

This runs against the documented route. It sends an Idempotency-Key so a retry of the submit returns the same job, polls with a bounded deadline, and sends the API key when it downloads the content URL.

import os, time, requests

BASE = "https://api.sume.com"
AUTH = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

def run(prompt, key):
    body = {"model": "seedance-2.5", "prompt": prompt, "duration": 5,
            "resolution": "720p", "aspect_ratio": "9:16"}
    r = requests.post(f"{BASE}/v1/videos", json=body, timeout=30,
                      headers={**AUTH, "Idempotency-Key": key})
    r.raise_for_status()
    url = r.json()["polling_url"]
    deadline = time.time() + 20 * 60
    while time.time() < deadline:
        time.sleep(10)
        s = requests.get(url, headers=AUTH, timeout=30).json()
        if s["status"] == "completed":
            v = requests.get(s["unsigned_urls"][0], headers=AUTH, timeout=300)
            v.raise_for_status()
            return v.content
        if s["status"] in ("failed", "cancelled"):
            raise RuntimeError(s.get("error") or s["status"])
    raise TimeoutError("still running; keep the job id, do not resubmit")

if __name__ == "__main__":
    open("out.mp4", "wb").write(run("A paper boat on a pond", "fal-port-001"))

Traps when you port

Two spellings differ: this route says cancelled with two Ls, while job webhooks and the jobs API say canceled. If you share one status handler between the poll route and the webhook, normalise them first. Second, the request is stricter than fal's: seed, size and a non-empty provider.options are refused with 400 on this route, so remove them from payloads you copy over. Third, the duration range belongs to the model; Seedance 2.5 takes 4 to 30 seconds.

On timeouts, never resubmit a paid request because your own process gave up. Keep the job id, poll again, and if you must repeat the submit, send the same Idempotency-Key.

When fal is the better fit

fal exposes many models behind per-model endpoints and fal's own client libraries, and its model list is its own. If you depend on a model that Sume's catalog does not list, the port is not possible, whatever the loop looks like. Read GET /v1/video-router/models first and port only the calls whose model id appears there.