Skip to main content
GET
/
api
/
stream
/
{filename}
Stream Video File
curl --request GET \
  --url https://api.example.com/api/stream/{filename}
{
  "404": {},
  "Content-Type": "<string>",
  "Content-Length": 123,
  "Content-Range": "<string>",
  "Accept-Ranges": "<string>"
}

​
Overview

This endpoint provides video streaming functionality with full HTTP range request support, enabling efficient video playback with seek capabilities. The server implements partial content delivery (HTTP 206 responses) when clients request specific byte ranges.

​
How HTTP Range Streaming Works

The streaming endpoint supports the HTTP Range header, which allows clients to request specific portions of a file. This is essential for:
  • Video player seeking: Jump to any point in the video without downloading the entire file
  • Bandwidth optimization: Download only the portions of the video being watched
  • Resume interrupted downloads: Continue from where playback stopped
  • Mobile-friendly playback: Efficient streaming on limited bandwidth connections

​
Range Request Flow

  1. Client sends a request with Range: bytes=start-end header
  2. Server parses the range and validates bounds
  3. Server reads the requested chunk from disk (default 64KB blocks)
  4. Server responds with HTTP 206 (Partial Content) and appropriate headers
  5. Client receives only the requested portion of the file

​
Endpoint

​
filename
string
required
The name of the downloaded video file. This should match the filename returned from a completed download task (format: title__task-id.ext).

​
Request Headers

​
Range
string
Optional HTTP range header to request a specific byte range of the file.Format: bytes=start-end
  • start: Zero-based byte offset (required)
  • end: Last byte to include (optional, defaults to end of file)
Examples:
  • bytes=0-1023 - First 1024 bytes
  • bytes=1024- - From byte 1024 to end of file
  • bytes=1000-2000 - Bytes 1000 through 2000 inclusive

​
Response

​
Without Range Header

Returns the complete file with HTTP 200.
​
Content-Type
string
video/mp4
​
Content-Length
integer
Total file size in bytes

​
With Range Header

Returns partial content with HTTP 206.
​
Content-Range
string
Indicates which bytes are being returned and the total file size.Format: bytes start-end/totalExample: bytes 0-1023/5242880 (first 1024 bytes of a ~5MB file)
​
Accept-Ranges
string
Always returns bytes to indicate the server supports range requests
​
Content-Length
integer
Size of the returned chunk in bytes (end - start + 1)
​
Content-Type
string
video/mp4

​
Implementation Details

​
Range Parsing

The server parses the Range header using a regex pattern: bytes=(\d+)-(\d*)
  • If end byte is not specified, it defaults to the last byte of the file
  • The end byte is clamped to file_size - 1 to prevent out-of-bounds reads
  • Invalid range formats fall back to returning the complete file

​
Chunk Streaming

The server streams the requested range in 64KB (65536 bytes) blocks: 
def iterfile():
    with open(filepath, "rb") as f:
        f.seek(start)
        remaining = chunk_size
        while remaining > 0:
            data = f.read(min(65536, remaining))
            if not data:
                break
            remaining -= len(data)
            yield data
This approach ensures:
  • Memory efficiency: Only 64KB in memory at a time
  • Responsive streaming: Data begins flowing immediately
  • Proper cleanup: File handle is closed after streaming completes

​
Examples

​
Basic Playback (Full File)

curl http://localhost:8001/api/stream/My_Video__123e4567-e89b-12d3.mp4
Returns HTTP 200 with the complete file.

​
Range Request (First 1MB)

curl -H "Range: bytes=0-1048575" \
  http://localhost:8001/api/stream/My_Video__123e4567-e89b-12d3.mp4
Response: 
HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1048575/52428800
Accept-Ranges: bytes
Content-Length: 1048576
Content-Type: video/mp4

[binary data...]

​
Range Request (Resume from 10MB)

curl -H "Range: bytes=10485760-" \
  http://localhost:8001/api/stream/My_Video__123e4567-e89b-12d3.mp4
Response: 
HTTP/1.1 206 Partial Content
Content-Range: bytes 10485760-52428799/52428800
Accept-Ranges: bytes
Content-Length: 41943040
Content-Type: video/mp4

[binary data...]

​
Seeking to Middle of Video

# Request bytes from ~25MB mark
curl -H "Range: bytes=26214400-27262975" \
  http://localhost:8001/api/stream/My_Video__123e4567-e89b-12d3.mp4
Response: 
HTTP/1.1 206 Partial Content
Content-Range: bytes 26214400-27262975/52428800
Accept-Ranges: bytes
Content-Length: 1048576
Content-Type: video/mp4

[binary data...]

​
Using with HTML5 Video Player

<video controls width="640">
  <source src="http://localhost:8001/api/stream/My_Video__123e4567-e89b-12d3.mp4" 
          type="video/mp4">
</video>
The browser automatically sends Range requests as the user seeks through the video.

​
Error Responses

​
404
error
File not foundThe specified filename does not exist in the downloads directory.
{
  "detail": "Archivo no encontrado"
}

​
Video Player Integration

Most modern video players automatically use range requests:
  • HTML5 <video> tag: Sends range requests when seeking
  • Video.js: Full range request support
  • Plyr: Automatic range handling
  • Mobile browsers: Optimize with range requests on cellular

​
Performance Considerations

  • Chunk size: 64KB blocks balance memory usage and streaming performance
  • Disk I/O: Sequential reads are optimized by the OS filesystem cache
  • Concurrent streams: Each request opens a separate file handle
  • No buffering: Streaming begins immediately, no file pre-loading required

Build docs developers (and LLMs) love

Get started for freeTalk to us