Stream
Stream
Bring video intelligence to your agents. Cloudflare Stream provides powerful video processing, live streaming, and media analysis capabilities that enable your AI agents to work with video content at scale. From processing user uploads to conducting live video analysis, Stream makes video a first-class data type for your agents.
Key Features
- Video Processing: Automatic transcoding, thumbnail generation, and format optimization
- Live Streaming: Real-time video streaming with global CDN delivery
- AI Integration: Built-in video analysis, transcript generation, and content recognition
- Global Delivery: Sub-second video startup from 330+ edge locations worldwide
- Security: Token-based access control and DRM protection for sensitive content
Getting Started
Wrangler Configuration
First, add Stream bindings in your wrangler.json:
Simple Video Upload Example
Upload and process a video with your agent:
MCP Integration
Stream capabilities exposed through MCP tools:
TypeScript API Reference
You can access the Stream API via the env of the Agent or MCP Tool:
Video Upload and Processing
upload(file: File, options?: UploadOptions): Promise<VideoAsset>
Uploads a video file for processing and storage. Automatically transcodes to multiple formats and generates thumbnails for optimal delivery across devices.
uploadFromUrl(url: string, options?: UploadOptions): Promise<VideoAsset>
Imports a video from an external URL. Useful for processing videos from user-provided links or integrating with other video platforms.
copy(options: { url: string, meta?: object, watermark?: { uid: string } }): Promise<VideoAsset>
Upload video from URL with optional metadata and watermark. Based on the /stream/copy endpoint.
getUploadUrl(options?: UploadOptions): Promise<UploadCredentials>
Generates a signed upload URL for direct creator uploads. Returns uploadURL and uid for client-side video uploads up to 200MB.
getDirectUpload(options: { maxDurationSeconds: number, watermark?: { uid: string } }): Promise<DirectUploadCredentials>
Creates unique one-time upload URLs for direct creator uploads.
Video Management
get(videoId: string): Promise<VideoAsset | null>
Retrieves detailed information about a video asset including processing status, metadata, and available formats.
list(options?: ListOptions): Promise<VideoAsset[]>
Lists video assets with filtering and pagination support. Supports search parameter for finding videos by name.
delete(videoId: string): Promise<void>
Permanently deletes a video asset and all associated data including transcoded versions and thumbnails.
update(videoId: string, meta: object): Promise<VideoAsset>
Updates video metadata such as name and custom properties.
Live Streaming
createLiveStream(options: LiveStreamOptions): Promise<LiveStream>
Creates a new live stream with RTMPS ingest endpoints. Returns stream keys and playback URLs for real-time video broadcasting. Based on the /live_inputs endpoint.
getLiveStream(streamId: string): Promise<LiveStream | null>
Retrieves live stream information including status, viewer count, and recording details.
updateLiveStream(streamId: string, updates: Partial<LiveStreamOptions>): Promise<LiveStream>
Updates live stream configuration such as recording settings, access controls, and metadata.
deleteLiveStream(streamId: string): Promise<void>
Deletes a live input. Live streams that are currently broadcasting will stop.
Video Editing
generateCaptions(videoId: string, language: string): Promise<Caption>
Generates AI-powered captions for videos. Supports languages: cs, nl, en, fr, de, it, ja, ko, pl, pt, ru, es. Based on captions API.
uploadCaptions(videoId: string, language: string, file: File): Promise<Caption>
Uploads WebVTT caption files for videos. Language must follow BCP 47 format.
getCaptions(videoId: string): Promise<Caption[]>
Lists all captions associated with a video including auto-generated and uploaded captions.
deleteCaptions(videoId: string, language: string): Promise<void>
Removes captions for a specific language from a video.
createWatermark(options: WatermarkOptions): Promise<Watermark>
Creates a watermark profile from image file or URL. Based on watermarks API.
getWatermark(watermarkId: string): Promise<Watermark>
Retrieves watermark profile information including size, position, and opacity settings.
listWatermarkslist(): Promise<Watermark[]>
Lists all watermark profiles for the account.
deleteWatermark(watermarkId: string): Promise<void>
Deletes a watermark profile. Won't remove watermarks from existing videos.
clipVideo(options: ClipOptions): Promise<VideoAsset>
Creates a new video by clipping a portion of an existing video. Based on video clipping API.
Video Downloads and Transforms
generateDownload(videoId: string): Promise<Download>
Enables MP4 downloads for a video. Returns download URL and processing status. Based on downloads API.
getDownloads(videoId: string): Promise<Download[]>
Retrieves all available download formats and their processing status for a video.
getThumbnail(videoId: string, options?: ThumbnailOptions): Promise<string>
Generates custom thumbnails at specified timestamps. Returns thumbnail URL.
Analytics
getAnalytics(options?: AnalyticsOptions): Promise<StreamAnalytics>
Retrieves video and live stream analytics data. Based on GraphQL Analytics API.
getLiveViewerCount(streamId: string): Promise<ViewerCount>
Gets current viewer count for a live stream. Based on live viewer counts.
Search and Discovery
search(query: string, options?: SearchOptions): Promise<VideoAsset[]>
Searches videos by name using the search parameter. Based on search API.
Examples
Video Content Analysis Agent
Live Streaming Event Agent
Video Tutorial Creation Agent
Best Practices
Video Processing Strategy
Security and Access Control
Performance Optimization
Advanced Configuration
Wrangler Configuration
Video Processing Options
- Qualities: 240p, 360p, 480p, 720p, 1080p, 1440p, 2160p
- Formats: MP4 (H.264), WebM (VP9), HLS adaptive streaming
- Thumbnails: JPEG, WebP, animated GIF previews
- Audio: AAC, MP3, automatic volume normalization
Limitations
- File Size: Maximum 5GB per video upload
- Duration: Maximum 6 hours per video
- Live Stream: Maximum 12 hours per stream
- Concurrent: 1,000 concurrent live streams per account
- Storage: Unlimited storage with automatic cleanup options
Related Services
- Storage (R2) - Raw video file storage and backup
- Analytics Storage - Video performance metrics
- Pub/Sub - Real-time stream event notifications