Bind to Workers API (2)

Bind to Workers API (2)

Last updated May 7, 2026 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"
    }
}

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

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

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.

id string
The unique identifier for the video.
creator string | null
A user-defined identifier for the media creator.
thumbnail string
The thumbnail URL for the video.
thumbnailTimestampPct number
The thumbnail timestamp percentage.
readyToStream boolean
Indicates whether the video is ready to stream.
readyToStreamAt string | null
The date and time the video became ready to stream.
status StreamVideoStatus
Processing status information. Refer to StreamVideoStatus.
meta Record<string, string>
A user modifiable key-value store.
created string
The date and time the video was created.
modified string
The date and time the video was last modified.
scheduledDeletion string | null
The date and time at which the video will be deleted.
size number
The size of the video in bytes.
preview string optional
The preview URL for the video.
allowedOrigins Array<string>
Origins allowed to display the video.
requireSignedURLs boolean | null
Indicates whether signed URLs are required.
uploaded string | null
The date and time the video was uploaded.
uploadExpiry string | null
The date and time when the upload URL expires.
maxSizeBytes number | null
The maximum size in bytes for direct uploads.
maxDurationSeconds number | null
The maximum duration in seconds for direct uploads.
duration number
The video duration in seconds. -1 indicates unknown.
input StreamVideoInput
Input metadata for the original upload. Refer to StreamVideoInput.
hlsPlaybackUrl string
The HLS playback URL for the video.
dashPlaybackUrl string
The DASH playback URL for the video.
watermark StreamWatermark | null
The watermark applied to the video, if any. Refer to StreamWatermark.
liveInputId string | null optional
The live input ID associated with the video, if any.
clippedFromId string | null
The source video ID if this is a clip.
publicDetails StreamPublicDetails | null
Public details associated with the video. Refer to StreamPublicDetails.

Bind to Workers API (2)

Bind to Workers API (2)

Setup

Methods

Binding-level methods

upload(url, params?)

createDirectUpload(params)

videos.list(params?)

Video-scoped methods

details()

update(params)

delete()

generateToken()

downloads

captions

Watermark methods

watermarks.generate(input, params)

watermarks.list()

watermarks.get(watermarkId)

watermarks.delete(watermarkId)

Examples

Upload a video from a URL

Create a direct upload

List videos

Get video details

Update video metadata

Delete a video

Generate a signed URL token

Upload captions

Generate AI captions

List and delete captions

Generate and list downloads

Create a watermark profile

List and delete watermark profiles

Type definitions

StreamVideo

`upload(url, params?)`

`createDirectUpload(params)`

`videos.list(params?)`

`details()`

`update(params)`

`delete()`

`generateToken()`

`downloads`

`captions`

`watermarks.generate(input, params)`

`watermarks.list()`

`watermarks.get(watermarkId)`

`watermarks.delete(watermarkId)`