skip to content

In Cloudflare Stream, what are the ways to upload a video, and when must an upload use the tus protocol?

level: juniorimportance: should knowfreq 28%

answer

  1. four routes into the library
  2. a size line at 200 MB
  3. Stream can fetch it for you
  4. chunks in 256 KiB multiples

basics

~10 s

Cloudflare Stream takes videos from the dashboard, a basic multipart POST, a link Stream downloads itself (/stream/copy), or the resumable tus protocol. Any file over 200 MB must use tus.

solid answer

~40 s

There are four ways in. The dashboard's **Quick upload** suits one-off files. A basic `POST` to `/accounts/{account_id}/stream` with the media in a `multipart/form-data` field named `file` works for files under 200 MB on a good connection. Upload via link (`POST .../stream/copy` with a `url`) makes Stream download the file itself, which suits videos already in a bucket. The **tus** protocol uploads in resumable chunks and is required above 200 MB, and recommended on unreliable networks; its chunks must be 5 MiB to 200 MiB and a multiple of 256 KiB, a final chunk excepted. Every route has a default 30 GB ceiling, and storage is billed by minutes of video, not bytes. When an end user uploads, the same POST and tus routes are offered through direct creator uploads.

code

bash · 11 lines
bash
# Basic upload of a file under 200 MB
curl --request POST \
  --header "Authorization: Bearer $API_TOKEN" \
  --form [email protected] \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/stream"

# Upload via link: Stream downloads the file itself
curl --request POST \
  --header "Authorization: Bearer $API_TOKEN" \
  --data '{"url":"https://media.example.com/lecture-02.mp4","meta":{"name":"Lecture 2"}}' \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/stream/copy"

go deeper

for a junior

Name the four routes and the 200 MB line: basic POST below it, tus above it, upload via link when the file already has a URL.

for a middle

Explain the tus chunk rules, the stream-media-id header and why storage is counted in minutes rather than bytes.

for a senior

Choose the route per source: link copies for bucket backfills, tus with aligned chunks for large or mobile uploads, and watch the 120-video encoding queue during bulk imports.

for a principal

Weigh which uploads go through your servers at all; copying by link or handing users direct upload URLs keeps large media off your own bandwidth and compute.

## The four upload routes Cloudflare Stream is a managed video service: you hand it an original file, it stores the original, encodes several quality levels and serves them over **HLS** and **DASH**. Getting the file in is the first decision, and Stream offers four routes. | Route | How it works | Size guidance | |---|---|---| | Dashboard quick upload | Drag a file onto the **Stream** page | One-off files, no code | | Basic `POST` | `multipart/form-data` request with the file in a field named `file` | Files under 200 MB | | Upload via link | `POST .../stream/copy` with a JSON `url`; Stream downloads the file | Files already reachable over HTTP | | **tus** (resumable) | Chunked, resumable upload protocol against the same `.../stream` endpoint | Required over 200 MB; recommended on unreliable links | A fifth path, **direct creator uploads**, is not a different transport: it is the basic `POST` or tus route offered to an *end user* through a one-time URL your backend creates, so your API token never leaves the server. ## Basic POST: the simple form upload The basic upload is one authenticated request to `https://api.cloudflare.com/client/v4/accounts/{account_id}/stream` with the API token in the `Authorization: Bearer` header and the media in a form field called `file`. It is the easiest route to script, but it is all-or-nothing: if the connection drops at 90%, the whole file goes again. The docs therefore draw the line at **200 MB**: below it a basic `POST` is fine on a good connection; above it you must switch to tus. ## Upload via link When the video already sits in a storage bucket, an R2 public URL or a content system that exposes a download link, you do not need to move the bytes through your own machine at all. A `POST` to `.../stream/copy` with `{"url": "...", "meta": {"name": "..."}}` makes **Stream fetch the file itself**. Two practical notes: - The URL must be downloadable by Stream over HTTP; a path on your laptop or a share link that rate-limits automated downloads will fail (a failed fetch ends with the error code `ERR_FETCH_ORIGIN_ERROR`). - Stream fetches the file once; after that the original lives in Stream, not at the source URL, and is billed by its duration. ## tus for large and fragile uploads **tus** is an open protocol for resumable uploads: the client creates an upload, then sends it in chunks and can resume from the last acknowledged byte after a failure. Stream requires it for any file over 200 MB and recommends it below that whenever the network is unreliable. Its chunk rules are specific to Stream: 1. A chunk must be at least **5,242,880 bytes** (5 MiB), unless the whole file is smaller than that. 2. **52,428,800 bytes** (50 MiB) is the suggested size when the connection is reliable. 3. A chunk may be at most **209,715,200 bytes** (200 MiB). 4. Every chunk size must be a **multiple of 256 KiB** (262,144 bytes); only a final chunk is exempt. The first tus request returns a `Location` header with the upload URL, and Stream also sends a `stream-media-id` header carrying the new video's ID. Read that header rather than parsing the `Location` URL, which the docs advise against. Optional settings travel in the `Upload-Metadata` header, as key and base64 value pairs: `name`, `requiresignedurls`, `allowedorigins`, `scheduleddeletion`, `thumbnailtimestamppct` and `watermark`. ## Limits that apply to every route - **30 GB** is the default maximum size of one upload. - By default up to **120 videos** may be queued or encoding at once; videos that are `ready`, `error` or `pendingupload` do not count. Going over returns `429` or `413` with details in the body. - **Storage is billed by duration, not size**: minutes of video stored, rounded up to the second. A 3 GB lecture and a 300 MB lecture of the same length cost the same to keep, and the extra quality levels Stream generates are not counted. - When the account's prepaid storage is used up, new uploads and new live streams are refused until storage is bought or videos are deleted (Enterprise contracts may allow uploads beyond the quota). ## Choosing a route 1. Is the file already at a URL Stream can download? Use upload via link. 2. Is it on your server and under 200 MB on a good connection? A basic `POST` is enough. 3. Is it larger, or is the network flaky? Use tus with a 256 KiB-aligned chunk size. 4. Is an end user uploading from a browser or app? Use a direct creator upload, which wraps the basic or tus route in a one-time URL. Resumable uploads as a general design pattern, with checksums and commit states, are covered with file upload ingestion; what is specific here is Stream's 200 MB line, its chunk arithmetic and the headers it returns.

  • How do you get the new video's ID from a tus upload to Stream?
    Read the `stream-media-id` header on the response to the first tus request. The `Location` header's URL may contain the ID too, but the docs advise against parsing it, so treat `stream-media-id` as the source of the video ID you store.
  • Does a 3 GB lecture cost more to store in Stream than a 300 MB one of the same length?
    No. Stream bills storage as minutes of video, rounded up to the second, regardless of file size, and ingress and encoding are free. The extra quality levels Stream encodes do not count toward storage either; only the original's duration does.

  • A basic POST upload handles any file size if the connection is fast.
  • Upload via link routes the file through your own server first.
  • tus chunks can be any size the client likes.
  • Stream storage is billed by gigabytes uploaded.
  • Parse the video ID out of the tus Location URL.