Skip to main content

​
Video Proxy

Proxy endpoint for streaming video content with support for HLS playlists and range requests.

​
Endpoint

GET /api/videoProxy

​
Authentication

No authentication required.

​
Rate Limiting

This endpoint is rate-limited. The default configuration allows:
  • 100 requests per 60 seconds per IP address
When rate limit is exceeded, the API returns a 429 Too Many Requests status with a Retry-After header.

​
Query Parameters

​
url
string
required
The URL of the video resource to proxy. Supports both HLS playlist files (.m3u8) and video segments.

​
Request Headers

​
Range
string
HTTP range header for partial content requests (e.g., bytes=0-1023). Enables video seeking and bandwidth optimization.

​
Response

​
Success Response

Status Code: 200 OK or 206 Partial Content (when Range header is provided) Headers:
​
Content-Type
string
MIME type of the resource:
  • application/vnd.apple.mpegurl for playlists
  • video/mp2t or other video MIME types for segments
​
Cache-Control
string
Caching policy:
  • Playlists: public, max-age=86400, s-maxage=86400 (24 hours)
  • Video segments: public, max-age=86400 (24 hours)
​
Accept-Ranges
string
Always set to bytes to indicate support for range requests.
​
Content-Length
string
Size of the response body in bytes.
​
Content-Range
string
Present when responding to range requests. Format: bytes <start>-<end>/<total>
​
Expires
string
Expiration date for playlist resources (24 hours from request).
Body:
  • For playlists: Modified M3U8 content with proxied URLs
  • For video segments: Binary video stream

​
Error Response

Status Code: 400 Bad Request, 404 Not Found, 429 Too Many Requests, or 500 Internal Server Error 
{
  "error": "Missing resource URL",
  "status": 400
}

​
Examples

curl -X GET "https://yourdomain.com/api/videoProxy?url=https://example.com/playlist.m3u8" \
  -H "Range: bytes=0-1023"

​
Usage in Video Players

import { MediaPlayer, MediaProvider } from '@vidstack/react';

<MediaPlayer
  src={`/api/videoProxy?url=${encodeURIComponent(playlistUrl)}`}
  aspectRatio="16/9"
>
  <MediaProvider />
</MediaPlayer>
The video proxy automatically handles HLS playlist manipulation, rewriting segment URLs to route through the proxy for seamless streaming.
Ensure the source video URL is accessible from your server. CORS restrictions on the source server may affect proxy functionality.

​
Features

  • Range Request Support: Enables video seeking and progressive loading
  • HLS Playlist Processing: Automatically rewrites playlist URLs
  • Caching: 24-hour cache for improved performance
  • Stream Processing: Efficient streaming without loading entire files into memory
  • Error Handling: Comprehensive error messages for debugging

Build docs developers (and LLMs) love

Get started for freeTalk to us