Skip to content
NewAgents for every project: your AI designs them, you watch them workAgents for every project
Docs · AI

Media

Video upload with HLS playback, and live channels with an RTMP ingest URL and HLS output.

View as Markdown
All topics
On this page

Create a video asset, upload the file to its one-time upload URL, and play it over HLS when it is ready. Live channels get an RTMPS ingest URL and a stream key; point your encoder at it and go live.

Videos and live channels are on Pro and up. On a plan without them, creating one answers 402 plan_limit with required_plan, and nothing is created. A workspace that still holds assets from a plan that had them gets the same answer when it asks for an upload URL or takes a channel live; videos already uploaded keep playing, and a stream can still be ended.

upload.mp4streaming pipelineHLS playbackRTMP ingestLIVEVOD + live in one service

In plain words

Upload videos and have them play smoothly on any screen, or stream live to your viewers.

For example: A yoga studio puts its class recordings online and streams its Sunday class live.

Details

  • Video only, up to 1 hour per upload. Kinds "image" and "audio" answer 501 — keep those files in Storage.
  • Status runs pending_upload → processing → ready. Size and duration appear once the file is processed.
  • Looking at a video (GET /api/media/:id) checks its status at most once every 15 seconds while it is still moving, and never again once it is ready or failed; in between, the last status answers, and recheck_after says how many seconds until the next real check. Poll no faster than that.
  • Each status check that is made, each "is an encoder connected?" check on a live channel, going live and a fresh upload URL count toward the workspace's data allowance (600 calls per 5 minutes, shared with database queries, vectors and memory, under the platform ceiling all workspaces share). When either says no, a look answers with the last status and a note saying when to look again, and going live or a fresh upload URL answers 429 rate_limited and changes nothing.
  • An expired upload URL is replaced with a fresh one (POST /api/media/:id/upload); once a file has arrived, no new URL is issued.
  • Stream keys and upload URLs are visible to developers and above, never to viewers.
  • Live channels do not record.
  • Assets per plan: 100 pro, 500 team, 1,000 scale. Each uploaded video and each live channel counts as one.

Reference

SDK
const { asset, uploadUrl } = await hk.media.create(project.id, { name: 'promo', kind: 'video' });
// POST multipart/form-data with field "file" to uploadUrl, then poll:
const { asset: ready } = await hk.media.get(asset.id);   // pending_upload → processing → ready
const live = await hk.media.create(project.id, { name: 'launch', kind: 'live' });   // ingest URL + stream key