Quickstart: stream a video in five minutes¶

This walkthrough takes you from an empty project to a playing video: get an API key, add a video, wait for encoding, and embed the player on a page.

Prerequisites: a HeapStream account with a project. Every video belongs to a project, and every API call below carries the project's id.

1. Create an API key¶

In the dashboard, open the API keys page and create a key. You get an id and a password — the API uses them as HTTP Basic Auth credentials (see API authentication):

curl -u "<apikey_id>:<apikey_password>" https://staging.heapstream.com/api/v1/project/

If the call returns your project list, you're authenticated. Note your project's id for the next step.

2. Add a video¶

GUIAPI

Open the project's upload page and drop a video file anywhere on the page — or switch to the From a URL tab and paste a link to a video file. The video appears in your library immediately and starts processing.

The fastest path is fetch by URL — one request, no file handling. Don't have a video at hand? Use the public Big Buck Bunny sample below.

curl -u "<apikey_id>:<apikey_password>" \
     -H "Content-Type: application/json" \
     -d '{
           "url": "https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_640x360.m4v",
           "metadata": { "title": "My first video", "public": true }
         }' \
     https://staging.heapstream.com/api/v1/project/<project_id>/video/fetch

The response is the new video object — note its id. (public: true makes the video viewable without a signed link, which keeps this walkthrough simple; the default is private.)

To upload a local file instead, use direct upload — the same options, as a resumable multipart upload.

3. Wait for encoding¶

The video starts at status waiting_for_upload, moves to queued once the bytes have arrived, and lands on completed when it's ready to stream. Check it:

curl -u "<apikey_id>:<apikey_password>" \
     https://staging.heapstream.com/api/v1/project/<project_id>/video/<video_id>

For the short sample above this takes well under a minute. In production, don't poll — configure a webhook and react to the video.status_update event instead.

4. Play it¶

Embed the player anywhere with an iframe:

<iframe src="https://staging.heapstream.com/e/<project_id>/<video_id>/"
        width="1280" height="720"
        allowFullScreen
        style="border: none;"
        allow="fullscreen; accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"></iframe>

Open the page — your video plays with the full player: quality selection, captions, scrub previews, and the rest. (The video object's link field from step 3 is exactly this URL, and the embed player page covers parameters, sizing, and customization.)

Next steps¶

Make it yours — skins, logos, and controls in the player: see the dashboard's Player Edit page.
Lock it down — private videos with signed, expiring URLs: Secure video playback.
See how it's watched — plays, watch time, and audience retention: Statistics.