API reference
Media privacy
Who can open what you generate, how long Sume keeps it, and how to delete it. Workspace settings, per-request options, signed links and deletes.
By default every output is public by link: anyone who has a file's URL can open it, and the URL does not expire. URLs cannot be guessed or listed, but treat them like a secret link.
You can make outputs private instead. A private output opens only through a signed link that expires, and every read of the job returns a fresh one.
Turn it on for your workspace
In the dashboard, open API keys → Media privacy, choose Private and save (team admins). The panel sets the first four fields of the table below; provider_copies follows the visibility.
GET and PATCH /v1/workspaces/{workspace_id}/media-settings read and change the same settings with the same field names. A key from Dashboard → API keys does not call them (403 open_key_route_not_allowed): use the panel, or send media with each request.
| Field | Values | Default |
|---|---|---|
output_visibility | public_by_link or private | public_by_link |
url_ttl_seconds | how long a signed link works, 60 to 604800 (7 days) | 3600 |
output_retention_seconds | delete outputs this long after the job finishes; null keeps them | null |
input_retention_seconds | delete uploads this long after upload; null keeps them | null |
provider_copies | delete_after_mirror (ask the provider to delete its copy once Sume has the file) or provider_default | delete_after_mirror when private |
Outputs made before a change keep their URLs. For an enterprise account Sume can set and lock the policy; a locked workspace cannot change it (409 media_settings_locked).
Per request
Every generation endpoint takes media, which overrides the workspace settings for that job:
delivery: "base64" adds base64 (the file's bytes) to each image of up to 20 MB when you read that job, beside url. A locked workspace accepts only stricter values.
url_ttl_seconds and delivery follow the job on every read: GET /v1/jobs/{id}, its status_url and result_url, and the response of a sync request such as POST /v1/images all return links with the same lifetime and the same base64. A list of jobs never carries base64.
What a private output looks like
- The link stops working at
expires_at(403). Read the job again (GET /v1/jobs/{id}or itsresult_url) for a fresh link; add?url_ttl_seconds=to ask for another lifetime. - Webhooks carry signed links too, with the same lifetime. Download the file when the webhook arrives.
- The job shows its policy as
media, includingdeletes_atwhen a retention applies. - To use a private output as the input of another request, send the signed link a read returned, before it expires.
Delete files
Both answer 204. The files are removed from Sume storage and from the CDN cache; the job and its billing stay, and later reads show media_deleted_at and no URL. Retention deletes the same way, automatically.
A key deletes the jobs and uploads it can read: its own workspace's, made by the member who made the key. Anything else answers 404. A job made before you turned private outputs on is deleted the same way.
Copies at providers
The model provider that renders a request may keep its own copy for a while. With provider_copies: delete_after_mirror, Sume deletes or shortens it once the output is stored: WaveSpeed (for example Seedream 5.5) predictions are deleted, fal and Higgsfield requests are stored for one day at most and then deleted. Some providers keep a copy we cannot delete (for example a BytePlus URL is valid for 24 hours); see Privacy.