List the Formats by Sume that return video, in Python

GET /v1/formats returns the Formats your key's workspace owns and the ready-made Formats by Sume, with keyset paging. Filter on handle == "sume" and io.output_kind == "video" to list the catalog Formats that return video. The script below does that with only the Python standard library.

import json
import os
import urllib.request

BASE = "https://api.sume.com/v1/formats?limit=50"


def fetch(url: str, key: str) -> dict:
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {key}"})
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)


def main() -> None:
    key = os.environ["SUME_API_KEY"]
    url = BASE
    found = []
    while url:
        body = fetch(url, key)
        for f in body["data"]:
            io = f.get("io") or {}
            if f.get("handle") == "sume" and io.get("output_kind") == "video":
                found.append((f["slug"], io.get("input_kind")))
        cursor = body.get("next_cursor")
        url = f"{BASE}&cursor={cursor}" if body.get("has_more") and cursor else None
    for slug, kind in sorted(found):
        print(slug, kind)


main()

What the key needs

The key needs the formats:read scope. Keys created before the Format API-call trigger shipped do not carry it, and you cannot add scopes to an existing key, so create a new one in the dashboard. A personal key lists your personal Formats and the catalog. A team key lists that workspace's Formats (Format API).

Fields worth reading

Each item carries more than a name. These are the ones that decide whether you can call it.

Why the script guards against null

io and showcase are null for Formats saved before those fields existed. That means not declared, not takes no input. The script uses f.get("io") or {} so an older Format is skipped instead of crashing. For those Formats, read the description and the call sheet page instead.

From the list to a run

Once you pick a slug, read it with GET /v1/formats/sume/{slug} to see its description, then call POST /v1/formats/sume/{slug}/runs with an instruction and an input object. Any key with formats:write can call a catalog Format, and the run, its media and its spend belong to your key. A slug that is not in the catalog answers 404 format_not_found.

Run times are minutes, not seconds, so design for a webhook or a polling loop from the start (Create a run).