# 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](https://docs.appsocom.dev/pricing.md)); 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](https://docs.appsocom.dev/webhooks.md) 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**: <span data-price="videoStorageGB">$0.033</span> 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**: <span data-price="videoProcessedMinutes">$0.0033</span> 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](https://docs.appsocom.dev/private-cloud.md) 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).
