Read a completed Sume /v1/videos poll response, field by field

A completed poll on GET /v1/videos/{jobId} returns a small object, and every field in it has one job: id and generation_id identify the job, polling_url is where you asked, status says completed, unsigned_urls is where the file lives, and usage.cost is what the workspace was billed. Store id and unsigned_urls[0], read usage.cost for your own books, and treat the rest as confirmation.

The sample in the Sume docs is short enough to read in one pass, so this note walks it line by line and then lists what a client should persist. It is for anyone writing the first poll loop, or reviewing one that only checks status.

The fields on a completed job

The docs' completed example carries id, generation_id, polling_url, status, model, unsigned_urls and usage. In that example id and generation_id are the same value, which is why one stored id is enough to resume; the docs do not promise they are always equal for every route, so keep both if you log both.

unsigned_urls are not public links

The name is easy to misread. An unsigned URL carries no signature, so it is not a shareable link: the docs show downloading the file from the content endpoint with an Authorization: Bearer header, for example GET /v1/videos/{jobId}/content?index=0. Fetch it from your server and put the bytes where your own users can reach them.

The model echo matters for Auto. A request sent with model: "sume/auto" reports sume/auto on the poll, and Sume does not disclose which family served it. Do not build logic on traits of the output to guess the model.

usage.cost is the billable amount

In the Sume differences table, billing is a workspace USD balance reserved on submit at provider list times 1.25, and usage.cost is the Sume billable amount. That is the number to reconcile against your balance; it is not the vendor price. The docs example shows a cost of 0.25 purely as a sample, so do not read it as a rate.

What a client should persist

Everything else on the page can be re-read from the job at any time. What the docs do not state is how long a job stays readable, so copy the file out when the job completes rather than assuming it stays fetchable.

• The job id the moment submit returns, before the first poll.
• The final status and, on failure, the error field the docs tell you to check.
• unsigned_urls[0], or the content endpoint path, plus the index you used.
• usage.cost, so a finance export does not need a second API call.

A short parsing example

In practice the parser is three lines: check status against the three terminal values, take unsigned_urls[0], and read usage.cost. Everything else is context. If you also want a single place to keep an audit trail, log id, generation_id, model and usage.cost together as one JSON line per finished job, and your reconciliation with the workspace balance becomes a sum over that file.

When a job fails, the same object carries an error field instead of URLs. The docs tell you to check it, and to confirm that any reference images were public HTTPS links in a supported format. Treat a missing unsigned_urls on a completed job as a bug to report, with the job id and request id, not as something to retry.