Scalar API Reference for the Sume OpenAPI JSON, with a Try It key
Scalar renders an OpenAPI document as an interactive reference with a test client. Point it at the Sume spec, and keep the Bearer key out of the page source.
The answer
Scalar's repository describes an interactive API reference generated from OpenAPI or Swagger documents, which includes an API testing tool and code examples for many languages. Give it Sume's spec at https://api.sume.com/reference/json and you get a browsable internal reference of the same operations.
Sume already hosts its own reference, so the reason to run Scalar is a private view: your wrapper routes, your examples, or an internal portal that combines Sume with your own API.
What Scalar gives you
The README lists a short set of properties. The ones that matter for a Sume reference are the renderer, the test client and the generated examples.
| Feature | Why it helps with Sume |
|---|---|
| Renders OpenAPI/Swagger documents | Shows all Jobs, image and media operations |
| Comes with an API testing tool | Send a status read from the page |
| Generates code examples for many languages | Share a starter call with a teammate |
| Integrates with your favorite framework | Embed in an existing docs site |
Handling the key
A Try It panel needs a credential. Enter your key at runtime in the panel, or have the page read it from a session you control, but never bake it into HTML or a public bundle. Sume accepts either a Bearer token or an x-api-key header, and sending both gives 401. Pick one and configure only that scheme in the panel.
A shared page that is open to everyone must not hold a real key at all. If many people will use it, make them paste their own.
What to expect in the reference
The document has 183 operations. The Jobs tag is the one to read first: it holds the list, read, status, result, cancel, webhook redeliver and events calls. The status response gives terminal, result_ready and next_poll_after_seconds; read them in the schema panel before you write polling code.
Try creates carefully. A create is a paid call. Set Idempotency-Key in the panel so a double click returns the same job rather than a second one.
Keep it current
A reference built from a fetched copy will age. Refetch on a schedule, and show the fetch date at the top of your page so readers know how fresh it is.
Adding your own context
The strongest reason to host your own reference is that you can add what the generated page cannot know: which model ids your product allows, which prompt templates you use, and which operations are off limits for your team. Put those in a short page next to the reference rather than editing the spec, so a refreshed spec never overwrites your notes.
Link out to Sume's own docs for the behaviours the spec only hints at, such as the jobs and results guide. The spec tells you the fields exist; the guide tells you how to use terminal, result_ready and the poll hints together.
Sources
Related posts
More in Developers
- Sume SDK wait timeouts: 20 min, 10 min, and the 90-minute run
subscribeFormatRun waits 20 minutes, waitForRun 10, waitForJob 20, yet a run lives up to 90. Which clock fires first and how to resume after a timeout.
- Fetch a Sume video output with the content endpoint index query
GET /v1/videos/{jobId}/content takes an index that defaults to 0. When it matters, how it lines up with unsigned_urls, and the curl line that saves a file.
- 768p on seedance-2.5 returns 400: use 720p, or pin a MiniMax id
Sume's resolution list is per model. seedance-2.5 takes 480p, 720p and 1080p; 768p exists on the MiniMax H3 ids and H3 Max Recast, and kling-3 has no 480p.
- Seedance 2.5 price calculator in Python: tokens to dollars
A 20-line Python function that turns Seedance 2.5 resolution, aspect ratio and seconds into the Sume billed price, checked against two known amounts.
Written by Sume