Watermark Profiles: A New Stream API Feature

Cloudflare Stream now includes a Watermarks API that lets developers add watermark images to videos programmatically at upload time. The API is designed for flexibility: you can request a simple placement ("top right") or control detail like "no more than 10% of the original video size, at 20% opacity." Watermarking is included at no additional cost.

Stream itself provides the video infrastructure—encoding, storage, delivery, and the Stream Player—so developers can skip the hard questions about affordability, encoding for varied connection speeds, and long-term pipeline maintenance. The Watermarks API extends this with two new capabilities:

  • A new /stream/watermarks endpoint for creating watermark profiles, each returning a uid.
  • Support for a watermark object containing the profile uid at upload time.

Creating a Watermark Profile

A watermark profile defines the watermark image and its display properties: positioning, padding, and scale. The example below creates a profile for a watermark in the lower left of the video.

curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/stream/watermarks \
  --header 'content-type: application/json' \
  --header 'x-auth-email: $CLOUDFLARE_EMAIL \
  --header 'x-auth-key: $CLOUDFLARE_KEY \
  --data '{
  "url": "https://storage.googleapis.com/zaid-test/Watermarks%20Demo/cf-icon.png",
  "name": "Cloudflare Icon",
  "opacity": 0.5,
  "padding": 0.05,
  "scale": 0.1,
  "position": "lowerLeft"
}'

The API response includes the profile metadata and its unique uid, which you’ll use in the next step.

Uploading with a Watermark

Once your profile exists, applying it is a matter of passing the watermark object during upload. Here is the sample video used below (unwatermarked):

Add Watermarks to your Cloudflare Stream Video Uploads Embedded Image - 3uJ5Kz

The upload request adds the logo from the earlier step as a watermark:

curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/stream/copy \
  --header 'content-type: application/json' \
  --header 'x-auth-email: $EMAIL \
  --header 'x-auth-key: $AUTH_KEY' \
  --data '{
  "url": "https://storage.googleapis.com/zaid-test/Watermarks%20Demo/The%20Internet%20was%20BuiltForThis.mp4",
  "watermark": {
    "uid": "a85d289c2e3f82701103620d16cd2408"
  }
}'

Result and Roadmap

The output is immediately viewable with the watermark applied.

Look for the Watermark API docs for more use cases. Future work includes animated watermarks and adding watermark support to the Stream Dashboard.