Pick a Format from the list: io profile and showcase before you run

You can choose a Format without running it. GET /v1/formats returns, for each one, an io object that says what it takes and makes, and a showcase that is a real output the Format produced when it was registered. Compare those against your job: a URL that should become a video, a product that should become an image. Then run only the one that fits.

The fields

The Format API docs define both fields in the list response.

A selection loop

List with curl -sS https://api.sume.com/v1/formats -H "Authorization: Bearer $SUME_API_KEY". Page with next_cursor while has_more is true. Filter in your own code on io.input_kind and io.output_kind, then open the showcase URL of each candidate to see whether the style fits. For the shortlist, fetch the call sheet at https://docs.sume.com/formats/{handle}/{slug}.

The list includes what your key's workspace owns plus the ready-made Formats by Sume at the sume handle, so a first integration can pick from the catalog without authoring anything.

• Match output_kind first: a video job needs a Format that makes video.
• Treat showcase: null as unknown, not as bad.
• Read the spend cap in generation_spend_cap_usd_micros before the first run.

Using the shortlist in code

Cache the listing for a short time, and key your own mapping on invoke_url rather than the vanity address. A small table in your config that maps a job type, such as product image to video, to one Format is easier to audit than picking at run time. Re-check it when you see a 404 or a 409, since owners can rename or switch off Formats they own.

Limits

io describes shape only; it does not say how good the result is for your brand. A showcase is one output, not a guarantee. A Format with io: null can still be fine, so fall back to its call sheet. And status and api_trigger_enabled in the same listing do not decide whether you can call it; see inactive Formats.