Sume asset download URL: 300 seconds and the 409 cases

GET /v1/assets/{id}/download-url gives you a short-lived signed GET link for an asset you uploaded to Sume. The link expires 300 seconds after it is issued unless the deployment overrides it, the response carries the exact expires_at, and the call answers 409 with asset_not_downloadable or asset_not_ready when the asset cannot be served that way. These routes are implemented but hidden from the public OpenAPI document, so treat them as a working surface rather than a documented contract; for generation inputs Sume's docs still prefer public HTTPS media URLs.

The behaviour below is from the route code on Sume's main branch, read 2026-10-11.

What does the response look like?

On success the body is { "data": { "asset": ..., "download": { "url", "method", "expires_at" } } }. method is always GET, so the URL needs no extra headers. The asset object is the same public shape the list and detail calls return, so you can check size_bytes and checksum_sha256 against the file you download.

A different asset id, or one from another workspace, is a 404. A Studio Agent turn credential can only read assets stamped for its own thread.

When does it return 409?

Two checks run after the asset is found, in this order. First, the asset must be a first-party upload with a storage key. An asset created by registering a remote URL has neither, and gets asset_not_downloadable with the message that only first-party uploaded assets can receive Sume download URLs. Sume does not proxy the remote file for you.

Second, the asset's status must be ready. An upload that is still pending_upload, or one that failed, gets asset_not_ready. Both errors include the asset's current status in their details, so a client can tell a pending upload from a failed one without a second call.

How should a client use the link?

Ask for the URL right before you need it and download immediately; do not store it. Five minutes is plenty for a normal fetch, and requesting a new link for a ready asset is cheap and repeatable.

The permanent url field on a completed asset is the Sume media address set when the upload was completed. The download-url call is the signed alternative for fetching the bytes with a link that stops working.

curl -s "https://api.sume.com/v1/assets/$ASSET_ID/download-url" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq -r '.data.download.url' \
  | xargs curl -sSfL -o clip.mp4

Why not just register a URL and download it back?

Registering with POST /v1/assets stores metadata only. It does not fetch, mirror or validate the media, and its status is registered, which is not generation-ready. Use the upload flow when you need Sume to hold the bytes, and public HTTPS URLs in generation requests when you do not.