Fetch video¶

If you already have videos stored on the web, you can pass an HTTP(S) link to the file. HeapStream will fetch the video, process it, and make it available for streaming.

GUIAPI

Open the upload page and switch to the From a URL tab. After submitting, the new video appears in an Added to your library panel with a link straight to its edit page.

Use the fetch video ⧉ API endpoint:

{
  "url": "https://example.com/videos/campaign.mp4",
  "metadata": {
    "title": "Campaign video",
    "public": false
  }
}

The response is the newly created video object — save its id to track progress.

Requirements on the URL¶

HTTP or HTTPS, pointing at a directly downloadable video file.
The URL is checked up front: if it can't be reached, the request fails with a 422 validation error on the url field, and the file's reported size must be within the 20 GB upload limit.
If your account doesn't have enough free storage, the request is rejected with 403 upload_quota_reached.

Options¶

Everything inside metadata is optional:

Field	Default	Effect
`title`	`null`	Title for the new video.
`public`	`false`	Make the video publicly viewable without a signed link.
`watermark_id`	`null`	Burn a watermark into the encoded output.
`auto_tt`	`null`	Language(s) for auto-generated captions; `null` uses the project settings.
`encoding_tier`	`null`	Encoding tier (`full` or `baseline`); `null` uses the project's tier.
`normalize_audio`	`false`	Apply audio normalization.

How the fetch proceeds¶

Fetching is asynchronous. The video is created immediately with status waiting_for_upload; HeapStream then downloads the file in the background, after which the video moves to queued and encoding starts, finishing at completed.

If the download fails (for example, the server returns an error), the video's status becomes errored, a fetch_http_error event is recorded on it with the response details, and a video.status_update webhook is sent. Use webhooks — not polling — to track the outcome.