Using Media

Direct upload

The bytes go from the browser to Cloudflare, not through your Worker.

Your Worker mints an upload URL for the right backend and records a row. The client uploads to that URL.

Which backend depends on the type, and that is the whole reason this capability exists separately from plain object storage: an image wants variants and transformation at serve time, a video wants adaptive playback, and a document wants neither.

The record is the thing you hold

A row in your own database, carrying what was uploaded, who owns it, the organization it was written under, who may read it, and — once enrichment runs — the text.

The store’s own id is what the asset is keyed by, because both image and video stores mint one rather than taking a name you choose. So there is nowhere to put a project segment, and ownership is carried in metadata instead: every asset is stamped with the project and the environment.

That stamp is merged last, so a caller’s own metadata cannot displace it — and a Worker that cannot name its project refuses to mint rather than writing an asset nobody can attribute.

It is weaker than a name, and deliberately so: nothing stops two projects’ assets sitting side by side, because ids are unique and neither can adopt the other’s. What the stamp buys is attribution — knowing which app owns an asset, and being able to sweep one app’s without touching another’s.

Who sees a record

An upload is private unless it says otherwise. POST /media takes a visibility — private, organization or public — and an upload that names none gets the project’s visibility.default. A level the project does not allow is refused.

GET /media lists the caller’s own records and their organization’s. Pass includePublic=true to add every public one. A record the caller may not read answers not found, so an id cannot be probed, and PATCH and DELETE belong to the owner and to a role holding media:manage. The full rules are in the reference.

A plan can cap how many records

Nothing limits the count until you ask. Compose payments, declare a mediaItems quota on your tiers and enforce the mediaItems meter, and POST /media refuses a create past the caller’s effective quota with payments/quota_exceeded (402). Nothing is written, and the upload URL already minted is left to expire unused. The count and the insert are one statement, so a burst of concurrent creates cannot walk past the limit. Under organization billing the number is the organization’s, and every member’s records count against it. A record held for a different organization than the one billed, or for none, is refused as core/internal, because it would never count. Tiers, quotas and features is where the number comes from.

Enrichment is opt-in, and runs on your bill

Three Workflows, each independent and each off unless you ask:

Alt text for images. Useful for accessibility, and useful for search.

Transcription for audio.

Text extraction for documents.

The inference runs on your own AI binding, which means it lands on your bill and your customers’ files never leave your infrastructure to be processed.

That is the same principle as the rest of the kit, applied to the one place where quietly calling somebody else’s API would be invisible and convenient.

Turning on one does not turn on the others, and none costs anything until a file of that type is uploaded.

Reading the text back

Records live in D1, so the text is queryable. Search a transcript with plain SQL, and join it against your own tables. Embed it instead and you have semantic search over your own media; either way the reference has the record shape.

There is no record store to choose any more: the kv one could not search, group or scope a read, and enrichment produces text specifically so that something can read it.

Transcripts and extracted text are the obvious thing to embed.

Compose vector and a spoken sentence in a video becoming a search result needs no glue between the two — you write the extracted text into the corpus and query it.

Chunking stays yours, because how a long document is split depends on what your documents are.

It presigns through the object-store seam

Media does not reimplement object storage. It uses the same seam, against its own bucket and its own credential name — and inherits none of that capability’s tables, routes, quotas or share links.

That separation matters if you compose both: a user’s uploaded document and a user’s uploaded avatar are different products with different lifecycles, and they do not share a quota by accident.

Serving

An image gets variants and transformation at serve time rather than at upload — so a new size is a URL rather than a re-upload of everything.

A video gets adaptive playback, so the bitrate follows the connection.

A non-public file is delivered through a signed, short-lived URL. Ask GET /media/:id/url for one; a public record gets a plain URL. There is no DRM.

What is not here

No editing. No cropping, trimming, filters or watermarks — though serve-time variants cover most of what people mean by this.

No moderation. The enrichment Workflows describe content; they do not judge it. Whether an image belongs on your platform is a policy question with a human at the end of it.

No live streaming. Video-on-demand only. Live is a different product with different economics.

ESC