Bind to Workers API

import { WranglerConfig, TypeScriptExample, Type, MetaInfo } from "~/components";

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:

• Upload videos from a URL and manage their lifecycle
• Create direct uploads for client-side uploads without having to expose API keys
• List and search videos
• Manage captions and downloads for videos
• Create and manage watermark profiles

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"
	}
}

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>.

• url (required): The URL of the video to upload.
• params (optional): A StreamUrlUploadParams object with the following properties:
  • allowedOrigins: Array of allowed origins for the video.
  • creator: Creator identifier.
  • meta: Arbitrary metadata object.
  • requireSignedURLs: Whether signed URLs are required.
  • scheduledDeletion: ISO 8601 timestamp for scheduled deletion.
  • thumbnailTimestampPct: Thumbnail timestamp as a percentage (0.0 to 1.0).
  • watermarkId: ID of a watermark profile to apply.

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._

• params (required): A StreamDirectUploadCreateParams object with the following properties:
  • maxDurationSeconds (required): Maximum duration of the uploaded video in seconds.
  • expiry (optional): ISO 8601 timestamp when the upload URL expires.
  • creator (optional): Creator identifier.
  • meta (optional): Arbitrary metadata object.
  • allowedOrigins (optional): Array of allowed origins for the video.
  • requireSignedURLs (optional): Whether signed URLs are required.
  • thumbnailTimestampPct (optional): Thumbnail timestamp as a percentage (0.0 to 1.0).
  • scheduledDeletion (optional): ISO 8601 timestamp for scheduled deletion.
  • watermark (optional): ID of a watermark profile to apply.

videos.list(params?)

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

• params (optional): A StreamVideosListParams object with the following properties:
  • limit: Maximum number of videos to return.
  • before: Return videos created before this ISO 8601 timestamp.
  • beforeComp: Comparison operator for before — eq, gt, gte, lt, or lte.
  • after: Return videos created after this ISO 8601 timestamp.
  • afterComp: Comparison operator for after — eq, gt, gte, lt, or lte.

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>.

• params (required): A StreamUpdateVideoParams object with the following properties:
  • allowedOrigins: Array of allowed origins for the video.
  • creator: Creator identifier.
  • maxDurationSeconds: Maximum duration in seconds.
  • meta: Arbitrary metadata object.
  • requireSignedURLs: Whether signed URLs are required.
  • scheduledDeletion: ISO 8601 timestamp for scheduled deletion.
  • thumbnailTimestampPct: Thumbnail timestamp as a percentage (0.0 to 1.0).

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.

• generate(downloadType?): Generate a download. downloadType is a StreamDownloadType of default or audio. Defaults to default. Returns Promise<StreamDownloadGetResponse>.
• get(): List existing downloads. Returns Promise<StreamDownloadGetResponse>.
• delete(downloadType?): Delete downloads. downloadType is default or audio.

captions

Namespace for caption operations on a video.

• upload(language, input): Upload a caption file for a BCP 47 language tag. input is a ReadableStream. Returns Promise<StreamCaption>.
• generate(language): Generate captions via AI for a BCP 47 language tag. Returns Promise<StreamCaption>.
• list(language?): List captions, optionally filtered by language. Returns Promise<StreamCaption[]>.
• delete(language): Delete captions for a language. Returns Promise<void>.

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>.

• input (required): A ReadableStream or URL string of the watermark image.
• params (optional): A StreamWatermarkCreateParams object with the following properties:
  • name: Name of the watermark profile.
  • opacity: Opacity of the watermark (0.0 to 1.0).
  • padding: Padding around the watermark as a proportion of the video resolution.
  • scale: Scale of the watermark as a proportion of the video resolution.
  • position: Position of the watermark — upperRight, upperLeft, lowerLeft, lowerRight, or center.

watermarks.list()

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

watermarks.get(watermarkId)

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

• watermarkId (required): The ID of the watermark profile.

watermarks.delete(watermarkId)

Delete a watermark profile. Returns Promise<void>.

• watermarkId (required): The ID of the watermark profile.

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);
	},
};

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);
	},
};

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);
	},
};

Get video details

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);
	},
};

Delete a video

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 });
	},
};

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);
	},
};

Generate AI captions

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);
	},
};

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 });
	},
};

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);
	},
};

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 });
	},
};

Type definitions

StreamVideo

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

• id

  • The unique identifier for the video.

• creator

  • A user-defined identifier for the media creator.

• thumbnail

  • The thumbnail URL for the video.

• thumbnailTimestampPct

  • The thumbnail timestamp percentage.

• readyToStream

  • Indicates whether the video is ready to stream.

• readyToStreamAt

  • The date and time the video became ready to stream.

• status

  • Processing status information. Refer to StreamVideoStatus.

• meta

  • A user modifiable key-value store.

• created

  • The date and time the video was created.

• modified

  • The date and time the video was last modified.

• scheduledDeletion

  • The date and time at which the video will be deleted.

• size

  • The size of the video in bytes.

• preview

  • The preview URL for the video.

• allowedOrigins

  • Origins allowed to display the video.

• requireSignedURLs

  • Indicates whether signed URLs are required.

• uploaded

  • The date and time the video was uploaded.

• uploadExpiry

  • The date and time when the upload URL expires.

• maxSizeBytes

  • The maximum size in bytes for direct uploads.

• maxDurationSeconds

  • The maximum duration in seconds for direct uploads.

• duration

  • The video duration in seconds. -1 indicates unknown.

• input

  • Input metadata for the original upload. Refer to StreamVideoInput.

• hlsPlaybackUrl

  • The HLS playback URL for the video.

• dashPlaybackUrl

  • The DASH playback URL for the video.

• watermark

  • The watermark applied to the video, if any. Refer to StreamWatermark.

• liveInputId

  • The live input ID associated with the video, if any.

• clippedFromId

  • The source video ID if this is a clip.

• publicDetails

  • Public details associated with the video. Refer to StreamPublicDetails.

StreamVideoStatus

Processing status information for a video.

• state

  • The current processing state.

• step

  • The current processing step.

• pctComplete

  • The percent complete as a string.

• errorReasonCode

  • An error reason code, if applicable.

• errorReasonText

  • An error reason text, if applicable.

StreamVideoInput

Input metadata for the original upload.

• width

  • The input width in pixels.

• height

  • The input height in pixels.

StreamPublicDetails

Public details associated with a video.

• title

  • The public title for the video.

• share_link

  • The public share link.

• channel_link

  • The public channel link.

• logo

  • The public logo URL.

StreamDirectUpload

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

• uploadURL

  • The URL an unauthenticated upload can use for a single multipart request.

• id

  • A Cloudflare-generated unique identifier for a media item.

• watermark

  • The watermark profile applied to the upload. Refer to StreamWatermark.

• scheduledDeletion

  • The scheduled deletion time, if any.

StreamCaption

Represents a caption or subtitle track for a video.

• generated

  • Whether the caption was generated via AI.

• label

  • The language label displayed in the native language to users.

• language

  • The language tag in BCP 47 format.

• status

  • The status of a generated caption.

StreamDownloadGetResponse

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

• default

  • The default video download. Only present if this download type has been created. Refer to StreamDownload.

• audio

  • The audio-only download. Only present if this download type has been created. Refer to StreamDownload.

StreamDownload

Represents a generated download for a video.

• percentComplete

  • Indicates the progress as a percentage between 0 and 100.

• status

  • The status of a generated download.

• url

  • The URL to access the generated download.

StreamWatermark

Represents a watermark profile.

• id

  • The unique identifier for a watermark profile.

• name

  • A short description of the watermark profile.

• opacity

  • The translucency of the image. A value of 0.0 makes the image completely transparent, and 1.0 makes the image completely opaque. Note that if the image is already semi-transparent, setting this to 1.0 will not make the image completely opaque.

• padding

  • The whitespace between the adjacent edges (determined by position) of the video and the image. 0.0 indicates no padding, and 1.0 indicates a fully padded video width or length.

• scale

  • The size of the image relative to the overall size of the video. 0.0 indicates no scaling, and 1.0 fills the entire video.

• position

  • The location of the image. Refer to StreamWatermarkPosition.

• size

  • The size of the image in bytes.

• height

  • The height of the image in pixels.

• width

  • The width of the image in pixels.

• created

  • The date and time a watermark profile was created.

• downloadedFrom

  • The source URL for a downloaded image. If the watermark profile was created via direct upload, this field is null.

StreamWatermarkPosition

The position of a watermark on a video.

• upperRight — Top-right corner of the video.
• upperLeft — Top-left corner of the video.
• lowerLeft — Bottom-left corner of the video.
• lowerRight — Bottom-right corner of the video.
• center — Center of the video. Note that center ignores the padding parameter.

StreamDownloadStatus

The status of a generated download.

• ready — The download is ready.
• inprogress — The download is being generated.
• error — An error occurred during generation.

StreamDownloadType

The type of download to generate.

• default — A video download.
• audio — An audio-only download.

StreamUrlUploadParams

Parameters for uploading a video from a URL.

• allowedOrigins

  • Lists the origins allowed to display the video. Enter allowed origin domains in an array and use * for wildcard subdomains. Empty arrays allow the video to be viewed on any origin.

• creator

  • A user-defined identifier for the media creator.

• meta

  • A user modifiable key-value store used to reference other systems of record for managing videos.

• requireSignedURLs

  • Indicates whether the video can be accessed using the ID. When set to true, a signed token must be generated with a signing key to view the video.

• scheduledDeletion

  • Indicates the date and time at which the video will be deleted. Omit the field to indicate no change, or include with a null value to remove an existing scheduled deletion. If specified, must be at least 30 days from upload time.

• thumbnailTimestampPct

  • The timestamp for a thumbnail image calculated as a percentage value of the video's duration. To convert from a second-wise timestamp to a percentage, divide the desired timestamp by the total duration of the video. If this value is not set, the default thumbnail image is taken from 0s of the video.

• watermarkId

  • The identifier for the watermark profile.

StreamDirectUploadCreateParams

Parameters for creating a direct upload.

• maxDurationSeconds

  • The maximum duration in seconds for a video upload.

• expiry

  • The date and time after upload when videos will not be accepted.

• creator

  • A user-defined identifier for the media creator.

• meta

  • A user modifiable key-value store used to reference other systems of record for managing videos.

• allowedOrigins

  • Lists the origins allowed to display the video.

• requireSignedURLs

  • Indicates whether the video can be accessed using the ID. When set to true, a signed token must be generated with a signing key to view the video.

• thumbnailTimestampPct

  • The timestamp for a thumbnail image calculated as a percentage value of the video's duration.

• scheduledDeletion

  • The date and time at which the video will be deleted. Include null to remove a scheduled deletion.

• watermark

  • The watermark profile to apply. Refer to StreamDirectUploadWatermark.

StreamDirectUploadWatermark

Watermark configuration for a direct upload.

• id

  • The unique identifier for the watermark profile.

StreamUpdateVideoParams

Parameters for updating a video.

• allowedOrigins

  • Lists the origins allowed to display the video. Enter allowed origin domains in an array and use * for wildcard subdomains. Empty arrays allow the video to be viewed on any origin.

• creator

  • A user-defined identifier for the media creator.

• maxDurationSeconds

  • The maximum duration in seconds for a video upload. Can be set for a video that is not yet uploaded to limit its duration. Uploads that exceed the specified duration will fail during processing. A value of -1 means the value is unknown.

• meta

  • A user modifiable key-value store used to reference other systems of record for managing videos.

• requireSignedURLs

  • Indicates whether the video can be accessed using the ID. When set to true, a signed token must be generated with a signing key to view the video.

• scheduledDeletion

  • Indicates the date and time at which the video will be deleted. Omit the field to indicate no change, or include with a null value to remove an existing scheduled deletion. If specified, must be at least 30 days from upload time.

• thumbnailTimestampPct

  • The timestamp for a thumbnail image calculated as a percentage value of the video's duration. To convert from a second-wise timestamp to a percentage, divide the desired timestamp by the total duration of the video. If this value is not set, the default thumbnail image is taken from 0s of the video.

StreamVideosListParams

Parameters for listing videos.

• limit

  • The maximum number of videos to return.

• before

  • Return videos created before this timestamp (RFC3339/RFC3339Nano).

• beforeComp

  • Comparison operator for the before field. Defaults to lt. Refer to StreamPaginationComparison.

• after

  • Return videos created after this timestamp (RFC3339/RFC3339Nano).

• afterComp

  • Comparison operator for the after field. Defaults to gte. Refer to StreamPaginationComparison.

StreamPaginationComparison

Comparison operators for pagination queries.

• eq — Equal to
• gt — Greater than
• gte — Greater than or equal to
• lt — Less than
• lte — Less than or equal to

StreamWatermarkCreateParams

Parameters for creating a watermark profile.

• name

  • A short description of the watermark profile.

• opacity

  • The translucency of the image. A value of 0.0 makes the image completely transparent, and 1.0 makes the image completely opaque. Note that if the image is already semi-transparent, setting this to 1.0 will not make the image completely opaque.

• padding

  • The whitespace between the adjacent edges (determined by position) of the video and the image. 0.0 indicates no padding, and 1.0 indicates a fully padded video width or length.

• scale

  • The size of the image relative to the overall size of the video. 0.0 indicates no scaling, and 1.0 fills the entire video.

• position

  • The location of the image. Refer to StreamWatermarkPosition.

Error handling

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

• code: A numeric error code.
• statusCode: An HTTP status code.
• message: A description of the error.
• stack: Optional stack trace.

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;
		}
	},
};