Bind to Workers API (4)·续

StreamVideoStatus

Processing status information for a video.

• state string
• The current processing state.
• step string optional
• The current processing step.
• pctComplete string optional
• The percent complete as a string.
• errorReasonCode string
• An error reason code, if applicable.
• errorReasonText string
• An error reason text, if applicable.

StreamVideoInput

Input metadata for the original upload.

• width number
• The input width in pixels.
• height number
• The input height in pixels.

StreamPublicDetails

Public details associated with a video.

• title string | null
• The public title for the video.
• share_link string | null
• The public share link.
• channel_link string | null
• The public channel link.
• logo string | null
• The public logo URL.

StreamDirectUpload

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

• uploadURL string
• The URL an unauthenticated upload can use for a single multipart request.
• id string
• A Cloudflare-generated unique identifier for a media item.
• watermark StreamWatermark | null
• The watermark profile applied to the upload. Refer to StreamWatermark.
• scheduledDeletion string | null
• The scheduled deletion time, if any.

StreamCaption

Represents a caption or subtitle track for a video.

• generated boolean optional
• Whether the caption was generated via AI.
• label string
• The language label displayed in the native language to users.
• language string
• The language tag in BCP 47 format.
• status 'ready' | 'inprogress' | 'error' optional
• 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 StreamDownload optional
• The default video download. Only present if this download type has been created. Refer to StreamDownload.
• audio StreamDownload optional
• 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 number
• Indicates the progress as a percentage between 0 and 100.
• status StreamDownloadStatus
• The status of a generated download.
• url string optional
• The URL to access the generated download.

StreamWatermark

Represents a watermark profile.

• id string
• The unique identifier for a watermark profile.
• name string
• A short description of the watermark profile.
• opacity number
• 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 number
• 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 number
• 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 StreamWatermarkPosition
• The location of the image. Refer to StreamWatermarkPosition.
• size number
• The size of the image in bytes.
• height number
• The height of the image in pixels.
• width number
• The width of the image in pixels.
• created string
• The date and time a watermark profile was created.
• downloadedFrom string | null
• 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' | 'upperLeft' | 'lowerLeft' | 'lowerRight' | 'center'

• 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' | 'inprogress' | 'error'

• 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' | 'audio'

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

StreamUrlUploadParams

Parameters for uploading a video from a URL.

• allowedOrigins Array<string> optional
• 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 string optional
• A user-defined identifier for the media creator.
• meta Record<string, string> optional
• A user modifiable key-value store used to reference other systems of record for managing videos.
• requireSignedURLs boolean optional
• 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 string | null optional
• 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 number optional
• 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 string optional
• The identifier for the watermark profile.

StreamDirectUploadCreateParams

Parameters for creating a direct upload.

• maxDurationSeconds number
• The maximum duration in seconds for a video upload.
• expiry string optional
• The date and time after upload when videos will not be accepted.
• creator string optional
• A user-defined identifier for the media creator.
• meta Record<string, string> optional
• A user modifiable key-value store used to reference other systems of record for managing videos.
• allowedOrigins Array<string> optional
• Lists the origins allowed to display the video.
• requireSignedURLs boolean optional
• 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 number optional
• The timestamp for a thumbnail image calculated as a percentage value of the video's duration.
• scheduledDeletion string | null optional
• The date and time at which the video will be deleted. Include null to remove a scheduled deletion.
• watermark StreamDirectUploadWatermark optional
• The watermark profile to apply. Refer to StreamDirectUploadWatermark.

StreamDirectUploadWatermark

Watermark configuration for a direct upload.

• id string
• The unique identifier for the watermark profile.

StreamUpdateVideoParams

Parameters for updating a video.

• allowedOrigins Array<string> optional
• 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 string optional
• A user-defined identifier for the media creator.
• maxDurationSeconds number optional
• 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 Record<string, string> optional
• A user modifiable key-value store used to reference other systems of record for managing videos.
• requireSignedURLs boolean optional
• 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 string | null optional
• 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 number optional
• 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 number optional
• The maximum number of videos to return.
• before string optional
• Return videos created before this timestamp (RFC3339/RFC3339Nano).
• beforeComp StreamPaginationComparison optional
• Comparison operator for the before field. Defaults to lt. Refer to StreamPaginationComparison.
• after string optional
• Return videos created after this timestamp (RFC3339/RFC3339Nano).
• afterComp StreamPaginationComparison optional
• Comparison operator for the after field. Defaults to gte. Refer to StreamPaginationComparison.

StreamPaginationComparison

Comparison operators for pagination queries.

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

• 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 string optional
• A short description of the watermark profile.
• opacity number optional
• 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 number optional
• 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 number optional
• 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 StreamWatermarkPosition optional
• 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:

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

Was this helpful?

YesNo

On this page

Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/stream/manage-video-library/bindings/#page","headline":"Bind to Workers API","description":"A binding connects your Worker to external resources on the Developer Platform, like Stream, R2 buckets, or KV namespaces.","url":"https://developers.cloudflare.com/stream/manage-video-library/bindings/","inLanguage":"en","image":"https://developers.cloudflare.com/stream/manage-video-library/bindings/og.png?v=92912e515ec36f0b","dateModified":"2026-05-07","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Vectorize Workers binding API for inserting, upserting, querying, and managing vectors. title: Vectorize API image: https://developers.cloudflare.com/vectorize/reference/client-api/og.png?v=984d6a4f3751e373

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/vectorize/llms.txt
Use this file to discover all available pages before exploring further.