How to Use the Fastio API for HLS Video Streaming

Most file storage APIs do not document or support HLS delivery out of the box. Upload a video to a standard cloud bucket, and you get a static file back. You cannot just link to that file to stream it to users. Standard downloads force the user's device to pull the entire file before playback begins. The alternative is basic progressive downloading, which stalls on slow connections.

Development teams often build complex processing pipelines to fix this. They upload the source file to a bucket, trigger a cloud function, and run the video through an intermediate transcoder. Finally, they store the resulting segments in a separate delivery bucket. This adds architectural overhead. It also drives up costs since you pay for storage twice and add processing fees for transcoding.

Maintaining this infrastructure takes time away from your core application. When a user uploads a video, your system has to manage state, track encoding progress, and catch failures. Manual infrastructure management becomes a bottleneck for teams building intelligent applications or agentic workflows. Instead, you need a platform that makes video files ready for playback the moment they finish uploading.

Fastio's API supports HLS video streaming so developers can deliver adaptive bitrate media directly from intelligent workspaces. HLS (HTTP Live Streaming) breaks a video down into small segments. These segments are usually a few seconds long. It then creates an M3U8 playlist file that lists them.

When you upload a video file into a Fastio workspace, the system automatically indexes it and prepares it for streaming. You skip configuring a separate transcoding service because the platform handles segmentation and playlist generation behind the scenes. Your application requests the HLS preview from storage and passes the redirected playlist to your frontend video player.

Fastio operates as an intelligent workspace rather than dumb storage, so this process happens automatically. Agents can upload generated videos, or humans can drop source files into a shared folder. The content becomes instantly available through the Fastio HLS integration. This unified approach removes the delay between upload and playback. It fits perfectly into fast-paced media workflows and AI-generated content pipelines.

Ready to simplify your video delivery?

Start streaming HLS video natively from your workspace. Authenticate with an API key and request the HLS preview.

See pricing

Before integrating HLS playback from Fastio, set up your workspace and authentication. Plan limits and trial details live on our pricing page.

Authentication uses API keys. Create a key in Settings > Devices & Agents > API Keys, or with POST /current/user/auth/key/. Send it on every authenticated call as Authorization: Bearer {api_key}. Developers building agentic workflows can use the MCP server at https://mcp.fast.io/mcp (Streamable HTTP), https://mcp.fast.io/mcp/key with a Bearer header in the client config, or https://mcp.fast.io/sse for legacy SSE.

Create a workspace specifically for your media assets to prepare your environment. This keeps video files isolated from other project data. Generate an API key once the workspace is active. If an AI agent manages your uploads, provide this key to the agent so it can drop files into the workspace and request HLS previews.

Requesting an HLS preview uses the storage preview route after your video is in the workspace.

Make a GET request to the HLS preview endpoint. You need the workspace ID and the file's node ID (both are 19-digit profile IDs). Keep the trailing slashes. The route looks like this in a typical cURL request:

curl -X GET "https://api.fast.io/current/workspace/{workspace_id}/storage/{node_id}/preview/hlsstream/read/" \
  -H "Authorization: Bearer YOUR_API_KEY"

If you are building your backend in Python, the same route applies. Follow the redirect to obtain the sub-file location:

import requests

workspace_id = "1234567890123456789"
node_id = "1234567890123456789"
url = (
    f"https://api.fast.io/current/workspace/{workspace_id}"
    f"/storage/{node_id}/preview/hlsstream/read/"
)
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers, allow_redirects=False)
print(response.status_code)
print(response.headers.get("Location"))

HLS previews return 307 Temporary Redirect to a sub-file endpoint. Point your player at that Location. The same preview route accepts thumbnail, image, mp4, hlsstream, audio, pdf, spreadsheet, and bin as the preview type. Share-scoped variants use share/{share_id} in place of workspace/{workspace_id}.

You need a compatible video player on the frontend after you follow the HLS preview redirect. Safari supports HLS natively in the standard HTML5 video tag. Most other browsers like Chrome and Firefox require a JavaScript library to parse the playlist and fetch the segments.

Video.js and hls.js are two of the most popular libraries for this task. Both work well with the playlist Location from the Fastio HLS preview.

Here is a basic example using hls.js. First, include the library in your project. Then, bind it to a standard video element.

if (Hls.isSupported()) {
  const video = document.getElementById('my-video');
  const hls = new Hls();

// Use the Location returned by the HLS preview redirect
  hls.loadSource(hlsPlaylistUrl);
  hls.attachMedia(video);

hls.on(Hls.Events.MANIFEST_PARSED, function() {
    video.play();
  });
}

This setup automatically handles adaptive bitrate switching. If the user's internet connection drops, the player requests lower-quality segments. This prevents the video from buffering.

Fastio is built for agentic workflows, which makes managing your media pipeline highly automated. Agents should use the MCP server rather than raw HTTP. You can configure this process by setting up storage for agents and providing the necessary access tokens.

Connect the agent to https://mcp.fast.io/mcp. Named mode exposes 19 tools, including upload, storage, ai, event, and how-to. A typical ingest call looks like this:

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"upload","arguments":{"action":"web-import","url":"https://example.com/clip.mp4",
 "profile_type":"workspace","profile_id":"1234567890123456789"}}}

After the file is in the workspace, request the HLS preview with GET /current/workspace/{workspace_id}/storage/{node_id}/preview/hlsstream/read/. Headless agents can run that same path through the execute tool. The agent can then store the redirect Location in a database or send it to a client via email.

For example, an agent can use the OpenClaw integration (clawhub install dbalve/fast-io) to watch a designated folder and run this ingest plus preview flow when a raw video arrives.

During multi-agent operations, Fastio's file locks prevent conflicts. If one agent is updating metadata while another attempts to move the file, the locking system ensures data integrity. Once an agent finishes building a media portal or workspace, it can transfer ownership entirely to a human user and keep only admin access for future maintenance.

Streaming from workspace storage works well for most applications, but developers should plan for edge cases. High-traffic applications can hit rate limits if they repeatedly call the preview endpoint. HTTP 429 with error code 1671 means you should back off until the x-ve-limit-expires header. Cache the HLS preview Location in your own database like Redis or PostgreSQL once you have it. This lets your frontend render the video player instantly without making redundant backend API calls.

Large files can take longer before playback can start. Show a loading state or a static thumbnail from GET /current/workspace/{workspace_id}/storage/{node_id}/preview/thumbnail/read/ in your UI.

Network restrictions on the client side can also cause playback issues. If a corporate firewall blocks the redirected host, the hls.js player will throw an error. Add error event listeners in your frontend code to catch these failures. Display a helpful message to the user instead of leaving them with a blank video player. Make sure your frontend application correctly handles Cross-Origin Resource Sharing (CORS) by serving the player from an authorized domain.