Python: find the Sume Format that takes your input and returns video

GET /v1/formats returns each Format with an io profile that names its input_kind and output_kind, so you can pick a Format by shape before you spend anything. The script below walks the keyset pages with next_cursor and yields the handle/slug of every Format that matches. Formats saved before registration existed return io: null, which means not declared, so the script skips them.

import json, os, urllib.request

def get(url):
    req = urllib.request.Request(
        url, headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"]})
    with urllib.request.urlopen(req) as res:
        return json.load(res)

def formats_by_io(kind_in, kind_out):
    cursor = None
    while True:
        url = "https://api.sume.com/v1/formats?limit=50"
        if cursor:
            url += "&cursor=" + cursor
        page = get(url)
        for f in page["data"]:
            io = f.get("io")
            if io and io["input_kind"] == kind_in and io["output_kind"] == kind_out:
                yield f"{f['handle']}/{f['slug']}"
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

if __name__ == "__main__":
    print(list(formats_by_io("text", "video")))

What the profile holds

Run it once in CI and diff the output over time. A change in the list of matching Formats is a signal that the catalog or your team's own Formats changed, which is cheaper to find out from a script than from a failed run.

How the paging works

The list returns the Formats your key's workspace owns plus the first-party catalog, in keyset pages. While has_more is true, send next_cursor back as cursor.

The key needs formats:read. A key made before the Format API call trigger shipped does not carry it, and you cannot add scopes to an existing key, so mint a new one.

Why not hard-code a slug

The catalog answers at the reserved sume handle, and any slug not in the published list answers 404 format_not_found. A filter on io keeps working when your own team adds Formats, and it tells you the shape of input to send: io is the only declared contract between a Format author and its callers, because the run body's input is free-form.

From the list to a call

Once you have a handle/slug, read GET /v1/formats/{handle}/{slug} for the description and cap. Then call POST /v1/formats/{handle}/{slug}/runs with an Idempotency-Key. Each list entry also carries generation_spend_cap_usd_micros, so you can filter out a Format whose cap is above what you want before you call it.