APPSOCOMDocs

Videos

Video on demand for recorded lessons, course videos and website clips. Your app gets an upload link, the browser sends the file straight to it, Appsocom Live turns it into HLS (360p and 720p, never above the original) with a poster image, and viewers watch with signed links that expire. Everything is stored in Cloudflare R2 and served by Appsocom Live, so there is no charge per minute watched. Nothing goes through your server but small JSON calls.

Videos need prepaid credit (see Pricing); they are off on the free plan.

Upload

Ask for an upload link from your backend with your project key, then give uploadUrl to the browser:

bash
curl -X POST https://api.appsocom.dev/videos/uploads -H "Authorization: Bearer $APPSOCOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxDurationSeconds":3600,"name":"Fractions, lesson 1","meta":{"course":"maths-jss1"},"uploadLength":48211230}'
json
{ "videoId": "5d5bc37ffcf54c9b82e996823bffbb81", "uploadUrl": "https://api.appsocom.dev/videos/upload/…?t=…", "protocol": "put", "expiresAt": "2026-11-20T20:00:00.000Z" }
  • maxDurationSeconds (required): the longest the video may be, up to 4 hours. A longer file is refused when it is converted.
  • name and meta (up to 10 string pairs of your own) come back with the video.
  • uploadLength: the file's size in bytes. Give it whenever you know it; for files over 95 MB it is required (up to 5 GB).

With "protocol": "put" the browser PUTs the file:

js
await fetch(uploadUrl, { method: "PUT", body: fileInput.files[0] });

With "protocol": "parts" (files over 95 MB) the answer also has partSize and parts. Send each slice, then finish:

js
const file = fileInput.files[0];
const parts = [];
for (let n = 1, at = 0; at < file.size; n++, at += partSize) {
  const res = await fetch(`${uploadUrl}&part=${n}`, { method: "PUT", body: file.slice(at, at + partSize) });
  parts.push(await res.json()); // {partNumber, etag}
}
await fetch(`${uploadUrl}&complete`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ parts }) });

A failed part can be sent again. Upload links work for 6 hours and for one video.

Bring in an existing video

bash
curl -X POST https://api.appsocom.dev/videos/copy -H "Authorization: Bearer $APPSOCOM_API_KEY" \
  -H "Content-Type: application/json" -d '{"url":"https://files.school.example/intro.mp4","name":"Welcome"}'

The file must be at a public https:// address.

Processing

A video's status is waiting (the upload hasn't finished), processing (with progress 0 to 100), ready or failed (with error). Converting takes roughly a quarter to half of the video's length.

Your webhook gets video_ready or video_failed once per video, with the video in data.video. You can also poll GET /videos/:videoId.

json
{
  "videoId": "5d5bc37ffcf54c9b82e996823bffbb81",
  "name": "Fractions, lesson 1",
  "status": "ready",
  "progress": 100,
  "error": null,
  "durationSeconds": 1834.2,
  "sizeBytes": 412000000,
  "width": 1280,
  "height": 720,
  "renditions": ["360p", "720p"],
  "meta": { "course": "maths-jss1" },
  "createdAt": "2026-11-20T14:00:00.000Z",
  "uploadedAt": "2026-11-20T14:03:10.000Z"
}

Once a video is ready the uploaded file is deleted, and sizeBytes is what is kept: the streaming files.

Play

Every video is private. When someone is allowed to watch, your backend asks for playback links for them:

bash
curl -X POST https://api.appsocom.dev/videos/5d5bc37ffcf54c9b82e996823bffbb81/playback \
  -H "Authorization: Bearer $APPSOCOM_API_KEY" -H "Content-Type: application/json" -d '{}'
json
{
  "videoId": "5d5bc37ffcf54c9b82e996823bffbb81",
  "hls": "https://api.appsocom.dev/videos/play/…/master.m3u8",
  "iframe": "https://api.appsocom.dev/videos/play/…/player",
  "thumbnail": "https://api.appsocom.dev/videos/play/…/poster.jpg",
  "expiresAt": "2026-11-20T16:01:08.000Z"
}
  • iframe is a ready-made player: <iframe src="…" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen></iframe>.
  • hls plays natively in Safari and on phones, and in other browsers with hls.js. Players switch between 360p and 720p to suit the connection.
  • Links last long enough to watch the video twice (at least an hour). Choose with "expiresInSeconds" (5 minutes to 24 hours). Make new links for each viewing rather than storing them.

Manage

GET /videos?after&limit your videos, newest first (pass next as after for the next page)
GET /videos/:videoId one video
PATCH /videos/:videoId {"name"} or {"meta"} (replaces it)
DELETE /videos/:videoId delete it and its files for good
GET /videos/usage bytes kept, videos, this month's meters and your caps

Server SDKs

ts
import { SfuKit } from "@appsocom/node";
const live = new SfuKit({ url: "https://api.appsocom.dev", adminKey: process.env.APPSOCOM_API_KEY });

const upload = await live.createVideoUpload({ maxDurationSeconds: 3600, name: "Lesson 1", uploadLength: file.size });
// give upload.uploadUrl to the browser, or send a file from your server:
await live.uploadVideoFile(upload, file);
// later, for a viewer:
const { hls, iframe } = await live.videoPlayback(upload.videoId);
go
up, err := client.CreateVideoUpload(ctx, sfukit.VideoUploadRequest{MaxDurationSeconds: 3600, Name: "Lesson 1"})
links, err := client.VideoPlayback(ctx, up.VideoID, 0)

Costs and limits

  • Storage: $0.033 per GB a month, counted daily. An hour of video is about 1 GB (360p and 720p together). Kept for 10 days of a 30-day month, a GB costs a third of the monthly price.
  • Converting: $0.0033 per minute of video, once, when it is uploaded.
  • Watching is free: there is no charge per view or per minute watched.
  • Projects can cap the GB kept (new uploads are refused past it) and the minutes converted per month. Videos stay stored, and keep counting, until you delete them.

Private Cloud

On Private Cloud videos are kept in your own account's R2 bucket (the STORAGE binding) and converted by your own bot container, so the Worker needs both. VIDEO_MAX_STORAGE_GB and VIDEO_MAX_PROCESSED_MINUTES_PER_MONTH cap the whole deployment (defaults 500 GB and 20,000 minutes a month), and VIDEO_MAX_DURATION_SECONDS the longest video (default 4 hours).