Sume job statuses: three vocabularies and a Python normalizer

A Sume video job reports its state in up to three vocabularies, and ported code that compares strings will miss one. GET /v1/videos/{id} returns pending, in_progress, completed, failed or cancelled. GET /v1/jobs/{id} returns queued, processing, completed, failed or canceled. GET /v1/jobs/{id}/status also carries a queue-style field, IN_QUEUE, IN_PROGRESS, COMPLETED, FAILED, CANCELED. The docs read 2026-10-06 say these map one to one.

That matters after the OpenAI Sora API ended on 2026-09-24 (Magic Hour tracker, read 2026-10-06), because a rewritten worker often ends up calling both the /v1/videos route and the shared jobs route, and the spelling of the cancelled state differs between them.

The mapping

The video route spells cancelled with two l letters and the jobs route with one, so compare through a normalizer, not a literal. The jobs status response also has booleans, terminal and result_ready, which the docs recommend polling on when you have them (Jobs and results, read 2026-10-06).

A normalizer

It lowercases, folds the spelling, and returns one of four states. It has no network call, so it runs as is and works as a unit test.

STATE = {
    "pending": "waiting", "queued": "waiting", "in_queue": "waiting",
    "in_progress": "running", "processing": "running",
    "completed": "done",
    "failed": "failed",
    "cancelled": "stopped", "canceled": "stopped",
}


def normalize(raw: str) -> str:
    try:
        return STATE[raw.strip().lower()]
    except KeyError:
        raise ValueError(f"unknown job status: {raw!r}") from None


assert normalize("IN_QUEUE") == "waiting"
assert normalize("cancelled") == normalize("canceled") == "stopped"
assert normalize("COMPLETED") == "done"
print("ok")

Why raise on an unknown word

An unknown status should stop the worker, not be treated as still running. A loop that keeps polling on a word it does not recognize can run until its deadline while the job has long since finished or been stopped. Raising gets the new word into your logs the first day it appears.

Keep the terminal set small: done, failed, stopped. Only done means a result exists. For failed, read the error field and decide whether to retry with the same idempotency key; for stopped, the job did not complete and you do not resubmit unless you meant to.

Where each route fits

• Use /v1/videos for new video code; its polling URL comes back in the submit response.
• Use /v1/jobs/{id}/status when one monitor watches video, image and audio jobs together, so one parser serves all.
• Use /v1/jobs/{id}/events for a timeline when you debug: job.created, job.queued, job.started, generation.submitted and the terminal events.
• Do not mix the spellings in one database column. Store the normalized state next to the raw word, and keep the raw word for support questions.

The earlier posts on the spelling difference and the retry policy by error category go deeper on those two edges.

Tests for the normalizer

A normalizer is a table lookup, so test the table, not the function body. List every word in the mapping above, feed each through the function, and assert the state it returns. Add one case with different capitalization, since the queue-style field is uppercase, and one with the unknown word that must raise.

The test is also documentation. When a new route or a new status word appears, a failing test says exactly where to add it, and the diff shows reviewers what changed in your model of the API. If you store the normalized state in a database, add a migration note too, because an old row with a raw word will otherwise look like a bug.

Share the normalizer as a small module used by every worker and dashboard in the company. Two services with two slightly different mappings are how a job ends up shown as running in one tool and cancelled in another, and one module with one test file removes that whole class of confusion.

• Cover all five states on each of the three vocabularies, fifteen words in total.
• Assert that cancelled and canceled map to the same state.
• Assert that an empty string and None raise, so a malformed response fails loudly.
• Keep the raw word in a second column; support questions are easier with the exact string the API sent.