INTEGRITY Cloudflare Docs

← Stream / stream / manage-video-library

Bind to Workers API

A binding connects your Worker to external resources on the Developer Platform, like Stream, R2 buckets, or KV namespaces.

For example, when you use Stream within Workers, you can:

Setup

The Stream binding is enabled on a per-Worker basis.

To bind Stream to your Worker, add the following to the end of your Wrangler configuration file:

{
	"stream": {
		"binding": "STREAM"
	}
}
[stream]
binding = "STREAM"

For more detailed information on configuring your Worker, refer to the Wrangler Configuration documentation.

Methods

Binding-level methods

The following methods are available on the env.STREAM binding directly.

upload(url, params?)

Upload a video from a URL. Returns Promise<StreamVideo>.

Throws: BadRequestError, QuotaReachedError, MaxFileSizeError, RateLimitedError, AlreadyUploadedError, InternalError.

createDirectUpload(params)

Create a basic direct upload URL for client-side uploads without an API key. Returns Promise<StreamDirectUpload> with uploadURL and id.

This method does not currently support files over 200MB. For larger direct uploads, refer to the API request for provisioning a TUS endpoint ↗._

videos.list(params?)

List all videos in the account. Returns Promise<StreamVideo[]>.

Video-scoped methods

Calling env.STREAM.video(id) returns a handle scoped to a single video, with the following methods.

details()

Get full video details. Returns Promise<StreamVideo>.

update(params)

Update video metadata. Returns Promise<StreamVideo>.

delete()

Delete a video and its copies. Returns Promise<void>.

generateToken()

Create a signed URL token for a video. Returns Promise<string>.

downloads

Namespace for download operations on a video.

captions

Namespace for caption operations on a video.

Watermark methods

The following methods are available on the env.STREAM.watermarks namespace.

watermarks.generate(input, params)

Create a watermark profile. Accepts either a ReadableStream or a URL string. Returns Promise<StreamWatermark>.

watermarks.list()

List all watermark profiles. Returns Promise<StreamWatermark[]>.

watermarks.get(watermarkId)

Get a single watermark profile. Returns Promise<StreamWatermark>.

watermarks.delete(watermarkId)

Delete a watermark profile. Returns Promise<void>.

Examples

Upload a video from a URL

export default {
	async fetch(request, env) {
		const video = await env.STREAM.upload("https://example.com/video.mp4", {
			creator: "user-123",
			meta: { category: "tutorial" },
			allowedOrigins: ["example.com"],
		});
		return Response.json(video);
	},
};
export default {
	async fetch(request, env) {
		const video = await env.STREAM.upload("https://example.com/video.mp4", {
			creator: "user-123",
			meta: { category: "tutorial" },
			allowedOrigins: ["example.com"],
		});
		return Response.json(video);
	},
};

Create a direct upload

export default {
	async fetch(request, env) {
		const directUpload = await env.STREAM.createDirectUpload({
			maxDurationSeconds: 300,
			creator: "user-123",
			meta: { source: "browser-upload" },
		});
		return Response.json(directUpload);
	},
};
export default {
	async fetch(request, env) {
		const directUpload = await env.STREAM.createDirectUpload({
			maxDurationSeconds: 300,
			creator: "user-123",
			meta: { source: "browser-upload" },
		});
		return Response.json(directUpload);
	},
};

List videos

export default {
	async fetch(request, env) {
		const videos = await env.STREAM.videos.list({
			limit: 10,
			after: "2025-01-01T00:00:00Z",
		});
		return Response.json(videos);
	},
};
export default {
	async fetch(request, env) {
		const videos = await env.STREAM.videos.list({
			limit: 10,
			after: "2025-01-01T00:00:00Z",
		});
		return Response.json(videos);
	},
};

Get video details

export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").details();
		return Response.json(videoDetails);
	},
};
export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").details();
		return Response.json(videoDetails);
	},
};

Update video metadata

export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").update({
			meta: { category: "updated-tutorial" },
			allowedOrigins: ["example.com", "*.example.com"],
		});
		return Response.json(videoDetails);
	},
};
export default {
	async fetch(request, env) {
		const videoDetails = await env.STREAM.video("VIDEO_ID").update({
			meta: { category: "updated-tutorial" },
			allowedOrigins: ["example.com", "*.example.com"],
		});
		return Response.json(videoDetails);
	},
};

Delete a video

export default {
	async fetch(request, env) {
		await env.STREAM.video("VIDEO_ID").delete();
		return new Response("Video deleted", { status: 200 });
	},
};
export default {
	async fetch(request, env) {
		await env.STREAM.video("VIDEO_ID").delete();
		return new Response("Video deleted", { status: 200 });
	},
};

Generate a signed URL token

export default {
	async fetch(request, env) {
		const token = await env.STREAM.video("VIDEO_ID").generateToken();
		return Response.json({ token });
	},
};
export default {
	async fetch(request, env) {
		const token = await env.STREAM.video("VIDEO_ID").generateToken();
		return Response.json({ token });
	},
};

Upload captions

export default {
	async fetch(request, env) {
		const captionResponse = await fetch("https://example.com/captions-en.vtt");
		const caption = await env.STREAM.video("VIDEO_ID").captions.upload(
			"en",
			captionResponse.body,
		);
		return Response.json(caption);
	},
};
export default {
	async fetch(request, env) {
		const captionResponse = await fetch("https://example.com/captions-en.vtt");
		const caption = await env.STREAM.video("VIDEO_ID").captions.upload(
			"en",
			captionResponse.body,
		);
		return Response.json(caption);
	},
};

Generate AI captions

export default {
	async fetch(request, env) {
		const caption = await env.STREAM.video("VIDEO_ID").captions.generate("en");
		return Response.json(caption);
	},
};
export default {
	async fetch(request, env) {
		const caption = await env.STREAM.video("VIDEO_ID").captions.generate("en");
		return Response.json(caption);
	},
};

List and delete captions

export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const captions = await video.captions.list();
		await video.captions.delete("en");
		return Response.json(captions);
	},
};
export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const captions = await video.captions.list();
		await video.captions.delete("en");
		return Response.json(captions);
	},
};

Generate and list downloads

export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const downloads = await video.downloads.generate();
		const audioDownloads = await video.downloads.generate("audio");
		const allDownloads = await video.downloads.get();
		return Response.json({ downloads, audioDownloads, allDownloads });
	},
};
export default {
	async fetch(request, env) {
		const video = env.STREAM.video("VIDEO_ID");
		const downloads = await video.downloads.generate();
		const audioDownloads = await video.downloads.generate("audio");
		const allDownloads = await video.downloads.get();
		return Response.json({ downloads, audioDownloads, allDownloads });
	},
};

Create a watermark profile

export default {
	async fetch(request, env) {
		const watermark = await env.STREAM.watermarks.generate(
			"https://example.com/watermark.png",
			{
				name: "My Watermark",
				opacity: 0.5,
				position: "lowerRight",
				padding: 0.05,
				scale: 0.1,
			},
		);
		return Response.json(watermark);
	},
};
export default {
	async fetch(request, env) {
		const watermark = await env.STREAM.watermarks.generate(
			"https://example.com/watermark.png",
			{
				name: "My Watermark",
				opacity: 0.5,
				position: "lowerRight",
				padding: 0.05,
				scale: 0.1,
			},
		);
		return Response.json(watermark);
	},
};

List and delete watermark profiles

export default {
	async fetch(request, env) {
		const watermarks = await env.STREAM.watermarks.list();
		const watermark = await env.STREAM.watermarks.get("WATERMARK_ID");
		await env.STREAM.watermarks.delete("WATERMARK_ID");
		return Response.json({ watermarks, watermark });
	},
};
export default {
	async fetch(request, env) {
		const watermarks = await env.STREAM.watermarks.list();
		const watermark = await env.STREAM.watermarks.get("WATERMARK_ID");
		await env.STREAM.watermarks.delete("WATERMARK_ID");
		return Response.json({ watermarks, watermark });
	},
};

Type definitions

StreamVideo

StreamVideo is returned by operations that retrieve or create a video. It contains the full metadata for a video.

StreamVideoStatus

Processing status information for a video.

StreamVideoInput

Input metadata for the original upload.

StreamPublicDetails

Public details associated with a video.

StreamDirectUpload

Returned by createDirectUpload(). Contains the upload URL and video identifier for a direct upload.

StreamCaption

Represents a caption or subtitle track for a video.

StreamDownloadGetResponse

An object with download type keys. Each key is optional and only present if that download type has been created.

StreamDownload

Represents a generated download for a video.

StreamWatermark

Represents a watermark profile.

StreamWatermarkPosition

The position of a watermark on a video.

'upperRight' | 'upperLeft' | 'lowerLeft' | 'lowerRight' | 'center'

StreamDownloadStatus

The status of a generated download.

'ready' | 'inprogress' | 'error'

StreamDownloadType

The type of download to generate.

'default' | 'audio'

StreamUrlUploadParams

Parameters for uploading a video from a URL.

StreamDirectUploadCreateParams

Parameters for creating a direct upload.

StreamDirectUploadWatermark

Watermark configuration for a direct upload.

StreamUpdateVideoParams

Parameters for updating a video.

StreamVideosListParams

Parameters for listing videos.

StreamPaginationComparison

Comparison operators for pagination queries.

'eq' | 'gt' | 'gte' | 'lt' | 'lte'

StreamWatermarkCreateParams

Parameters for creating a watermark profile.

Error handling

Errors throw a StreamError, which extends the standard Error interface with additional information:

The following error subtypes may be thrown:

Error type Description
InternalError An internal server error occurred.
BadRequestError The request was malformed or contained invalid parameters.
NotFoundError The requested resource was not found.
ForbiddenError The request was not authorized.
RateLimitedError The request was rate limited.
QuotaReachedError The account has reached its video quota.
MaxFileSizeError The uploaded file exceeds the maximum allowed size.
InvalidURLError The provided URL is invalid or unreachable.
AlreadyUploadedError The video has already been uploaded.
TooManyWatermarksError The account has reached the watermark profile limit.

Use a try...catch block to handle errors:

export default {
	async fetch(request, env) {
		try {
			const videoDetails = await env.STREAM.upload(
				"https://example.com/video.mp4",
			);
			return Response.json(videoDetails);
		} catch (e) {
			if (e instanceof Error) {
				return new Response(`Stream error: ${e.message}`, { status: 500 });
			}
			throw e;
		}
	},
};
export default {
	async fetch(request, env) {
		try {
			const videoDetails = await env.STREAM.upload("https://example.com/video.mp4");
			return Response.json(videoDetails);
		} catch (e) {
			if (e instanceof Error) {
				return new Response(`Stream error: ${e.message}`, { status: 500 });
			}
			throw e;
		}
	},
};