Sume API media URL rules: which URLs each endpoint accepts

The Sume API accepts two kinds of media URL. Most generation endpoints, captions, and Format or Agent attachments take a fetchable public HTTPS URL, while the media tools (trim, audio detach, filter, frames, inspect, and the Timeline routes) accept only media.sume.com URLs that already belong to your workspace, such as the output of an earlier Sume job.

The table comes from Sume's Media inputs page, each endpoint's docs page, and the OpenAPI reference, read on 2026-09-27. How the avatar, face-swap, and caption fields and Format attachments work is covered in Video API media inputs and outputs; this page is the endpoint-by-endpoint rule.

Which URL does each endpoint accept?

Public HTTPS means a fetchable HTTPS URL on the open internet. Workspace media.sume.com means an artifact or asset your workspace already has on that host; other hosts are refused. Each row links the post that covers that endpoint.

What counts as a public HTTPS URL?

The docs call these fetchable public HTTPS URLs: the file has to load for an anonymous request from the open internet.

• Localhost, private-network, non-HTTPS, and signed or private URLs are rejected before generation submission, and so are mismatched content types.
• In current code, every URL field in the table except attachments also refuses embedded credentials, a port other than the default 443, and a host name ending in .local, .internal, or .test, and caps the URL at 2,048 characters.
• Format and Agent attachments are fetched when you create the run, so they must be reachable without auth. An unreachable host, hotlink protection, or a non-2xx answer fails the create with 502 attachment_fetch_failed.

Why do trim, frames, and Timeline refuse my URL?

The media tools have no open-internet fetch, so an off-host URL such as https://example.com/clip.mp4 is rejected at admit. These are the URL codes they return:

• unsupported_media_source: the URL is not on the Sume media host.
• source_not_found: a dead or foreign media.sume.com URL.
• unsupported_media_type: on trim, detach, and filter, the file's HEAD response is not a video.
• On POST /v1/video-frames, a video_url that is not on media.sume.com is a plain schema 400.

Can I test a URL without paying?

Yes. POST /v1/video-filter/check runs the same Sume-host and HEAD preflight as a filter encode and returns diagnostics instead of a 400, without creating a job or reserving credits. POST /v1/timeline-1.0/plan runs the Sume-host URL checks for a whole timeline, also unbilled.

curl -X POST https://api.sume.com/v1/video-filter/check \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "ops": [{ "op": "dim", "amount": 0.45 }]
  }'

How do I get a file onto media.sume.com?

Start from an earlier Sume output. Sume mirrors generated outputs into Sume-owned media URLs before it exposes them in results, and completed jobs carry those files as artifacts under media.sume.com. A generated clip, a captioned video, or an earlier trim can feed the next media tool. For a POST /v1/videos clip, read the artifact from GET /v1/jobs/{id}/result, as chaining clips from the last frame shows.

• Sume's asset upload routes are implemented but hidden from the public OpenAPI, and the docs say not to treat them as public contract.
• Store the Sume URL, not a raw provider URL. Raw provider URLs and provider task URLs are not part of the public result contract.