# rehelios — Complete product reference

> rehelios is a hosted video infrastructure platform for developers and AI agents. Upload a video and rehelios transcodes it into adaptive HLS (plus optional MPEG-DASH and progressive MP4), stores it durably, and delivers it from a global CDN with signed playback, subtitles, chapters, analytics, and a REST API. Every capability is operable programmatically — by your backend, by the `@rehelios/cli` command line, or by an AI agent through an MCP server.

## What problem does rehelios solve?

Building a production video stack requires assembling upload handling, a transcoding pipeline, durable storage, a CDN, access control, captions, analytics, and an API surface. Teams typically stitch together multiple services and write substantial glue code. rehelios is that entire stack as a single hosted service: one API key, one billing line, zero infrastructure to operate.

## Core features

### Upload
- Resumable multipart uploads via a TUS-compatible flow.
- The origin server never handles the raw bytes — uploads go straight from the client to object storage, so bandwidth costs and latency are kept off the application server.
- Supports large files; interrupted uploads resume from where they left off.
- **URL import**: `POST /v1/videos/import` accepts a public HTTP(S) URL instead of a file upload. rehelios fetches the source server-side and runs the full transcode pipeline. Useful for migrating existing video libraries from S3, R2, or any CDN without re-uploading from a client.

### Transcoding
- Single-pass ffmpeg adaptive bitrate ladder: 240p, 360p, 480p, 720p, 1080p.
- Output formats: adaptive HLS (default), MPEG-DASH (optional), progressive MP4 (optional).
- Encoding is free — there is no per-minute transcoding charge, ever.
- A webhook (`video.ready`) fires when encoding completes; another (`video.failed`) fires on failure.

### Delivery
- Video segments are cached on a global CDN with long TTLs.
- Manifests are kept fresh so ABR players always have accurate track data.
- Edge bandwidth is metered and surfaced in analytics.

### Playback and access control
- `GET /v1/videos/{id}` returns `playbackUrl` — an absolute HLS master URL ready for any player. Read this field; never construct URLs from storage paths.
- **Public videos** (`visibility: "public"`) play from `playbackUrl` with no auth, and embed with a plain `<iframe>` at `https://app.rehelios.com/embed/{id}`.
- **Private videos** authorize at the edge in one of two ways:
  - **Signed token** — `POST /v1/videos/{id}/playback-token` and append the JWT as `?token=` to `playbackUrl`. The edge validates it and re-mints a longer session token for the playlist's child URIs, so a single request covers the whole watch.
  - **Domain allowlist (Referer/Origin)** — Bunny-style. Add allowed hostnames in the dashboard (org setting `playbackDomains`); then the plain `playbackUrl` plays token-less from those sites, with a stable URL that never expires. An empty allowlist (or `*`) allows any origin.
- Auth is cookie-free (the token/Referer travels per request), so playback works inside cross-site embeds even with third-party cookies blocked (Brave/Safari/Chrome).
- The edge only serves the encoded HLS/DASH/MP4/subtitles/thumbnails; original uploads are never exposed.

### Captions and chapters
- Upload VTT or SRT subtitle files, or trigger auto-caption generation.
- Multi-language support; captions are wired into the HLS manifest.
- Per-video chapter markers for seekable content.

### Collections
- Group videos into named collections for playlist-style organization.

### Analytics
- Per-video metrics: views, watch time, completion rate, top countries.
- Account-wide aggregate view of the same metrics.
- Edge bandwidth consumed per video and account-wide.
- Data rolls up daily; no sampling.

### REST API
- Full REST API authenticated with scoped API keys.
- OpenAPI reference published at https://api.rehelios.com/openapi.
- Endpoints cover: videos, uploads, captions, chapters, collections, webhooks, analytics, API keys.

### Webhooks
- HMAC-signed webhooks delivered over HTTPS.
- Events: `video.ready`, `video.failed`, `caption.ready`.
- Signature verified with a per-endpoint secret; retry on failure.

## Pricing

rehelios uses a pure usage-based model with no per-seat licensing.

| Resource | Price |
|---|---|
| Storage | $0.01 per GB per month |
| Delivery (bandwidth) | $0.005 per GB streamed |
| Encoding | Free |
| Monthly minimum | $1.00 |

### Billing examples

- **10 GB stored, 50 GB delivered in a month:** (10 × $0.01) + (50 × $0.005) = $0.10 + $0.25 = $0.35 → billed at the $1 monthly minimum.
- **100 GB stored, 500 GB delivered:** (100 × $0.01) + (500 × $0.005) = $1.00 + $2.50 = $3.50.
- **1 TB stored, 10 TB delivered:** (1024 × $0.01) + (10240 × $0.005) = $10.24 + $51.20 = $61.44.

The player, signed playback, the REST API, webhooks, captions, chapters, and analytics are all included at no extra charge.

## How it works — step by step

1. **Upload or import** — Either: (a) call `POST /v1/videos` to create a video record and upload the file directly to object storage via TUS — your server never touches the bytes; or (b) call `POST /v1/videos/import` with a public URL and rehelios fetches and stores the file server-side.
2. **Transcode** — A background worker picks up the original file, runs it through the adaptive bitrate ladder with ffmpeg, and writes the resulting HLS segments, manifests, optional DASH manifest, and optional MP4 back to durable storage.
3. **Deliver** — Segments are served from a global CDN with long cache TTLs. rehelios signs manifests and rotates signed cookies at the edge.
4. **Embed or API** — `GET /v1/videos/{id}` returns `playbackUrl`, an absolute HLS master URL ready for any player (append a signed token for private videos). Or embed the hosted player with a simple `<iframe>` pointing at `https://app.rehelios.com/embed/{id}`. The whole workflow (list, update, delete, caption, analytics) is also driven through the REST API.

## Comparison with alternatives

| Capability | rehelios | Cloudflare Stream | Bunny Stream |
|---|---|---|---|
| Storage billing | $0.01 / GB·month | Per minute stored | $0.01 / GB·month |
| Delivery billing | $0.005 / GB | Per minute delivered | $0.005 / GB |
| Encoding fees | Free | Included (per-minute rate) | Free |
| Adaptive HLS | Yes | Yes | Yes |
| MPEG-DASH output | Yes | No | Yes |
| Signed / token playback | Yes | Yes | Yes |
| REST API + webhooks | Yes | Yes | Yes |
| Self-serve, no sales call | Yes | Yes | Yes |

### Why choose rehelios over Cloudflare Stream?
Cloudflare Stream charges per minute of video stored and per minute delivered. A long, rarely watched video costs the same as a short, viral one. rehelios bills by the gigabyte, so costs scale with actual storage footprint and actual bytes delivered — not runtime. For most libraries of mixed-length content this means significantly lower bills. Cloudflare Stream also does not support MPEG-DASH output natively.

### Why choose rehelios over Bunny Stream?
Bunny Stream and rehelios share the same per-gigabyte pricing model. rehelios differentiates on developer experience: a cleaner REST API design, OpenAPI documentation, HMAC-signed webhooks, auto-captions, and a fully self-serve onboarding flow with no support ticket required to unlock features.

### Why choose rehelios over Mux?
Mux targets enterprise customers with per-minute pricing starting higher than rehelios. rehelios is designed for developer teams that want the full feature set without per-seat licenses, without per-minute encoding costs, and without a sales process.

## Use cases

- **Online course platforms** — Upload lecture recordings, auto-generate captions, organize into collections, gate playback with signed tokens per enrolled student.
- **SaaS applications with video** — Product demos, onboarding walkthroughs, screen recordings. Integrate via the REST API; receive `video.ready` webhooks to update your database.
- **Media and publishing** — Upload news clips or documentary segments, deliver globally with ABR, track completion rates per video.
- **Sports and live events** — Serve recorded highlights or VOD replays from the same infrastructure as live content.
- **Developer tools and documentation** — Host tutorial videos alongside code docs; embed with a plain iframe or signed token.
- **Social platforms** — Users upload video; your backend creates a rehelios video via API, receives a `video.ready` webhook, and surfaces the HLS URL to the player.

## Developer integration guide

### 1. Get an API key

Sign up at https://app.rehelios.com and create a scoped API key from the dashboard.

### 2. Create a video and upload

The simplest path — let the CLI handle the multi-step presigned upload and the
ready-poll for you:

```bash
npx @rehelios/cli upload ./product-demo.mp4 --wait   # prints the embed URL
```

Doing it directly over HTTP is a three-step presigned multipart flow:

```bash
# 1. create the video record
curl -X POST https://api.rehelios.com/v1/videos \
  -H "Authorization: Bearer rh_live_..." -H "Content-Type: application/json" \
  -d '{"title": "product-demo.mp4"}'                       # → { id }

# 2. POST /v1/videos/{id}/upload-init  → presigned part URLs + uploadId
#    PUT each part straight to its presigned R2 URL (capture each ETag)
# 3. POST /v1/videos/{id}/upload-complete  with { uploadId, parts }  → status: queued
```

Or import from a public URL in one call: `POST /v1/videos/import` with `{ "url": "https://…" }`.
After encoding, `GET /v1/videos/{id}` returns `playbackUrl` (an absolute HLS URL).

### 3. Handle the webhook

```json
{
  "event": "video.ready",
  "videoId": "vid_abc123"
}
```

The webhook payload is intentionally minimal. On `video.ready`, call `GET /v1/videos/vid_abc123` — the response includes `playbackUrl`: an **absolute** HLS master playlist URL ready to hand to any player (e.g. `https://video.rehelios.com/{orgId}/vid_abc123/hls/master.m3u8`). Do not construct this URL yourself; read `playbackUrl` from the response. There is also `posterUrl`, and `mp4Path` for a progressive download.

### 4. Authorize private playback

Two options (see "Playback and access control"):

```bash
# Option A — signed token: mint one and append it to playbackUrl
curl -X POST https://api.rehelios.com/v1/videos/vid_abc123/playback-token \
  -H "Authorization: Bearer rh_live_..."
# Returns a JWT; append as ?token=<jwt> to playbackUrl

# Option B — domain allowlist (Bunny-style, stable token-less URL):
# set your allowed domains once in the dashboard (Settings → Playback domains),
# then hand the plain playbackUrl (no token) to the player. An empty list
# allows any origin.
```

### 5. Embed

```html
<!-- Public video — iframe embed -->
<iframe src="https://app.rehelios.com/embed/vid_abc123" allowfullscreen></iframe>

<!-- Private video — playbackUrl from GET /v1/videos/{id}. With a domain allowlist
     set, use it as-is; otherwise append a signed ?token=<jwt>. -->
<video>
  <source src="https://video.rehelios.com/{orgId}/vid_abc123/hls/master.m3u8"
          type="application/vnd.apple.mpegurl" />
</video>
```

## CLI and MCP server (agent-native)

rehelios is designed to be driven by an AI agent, not just a human at a dashboard. One npm package — `@rehelios/cli` — is both a command-line tool and a Model Context Protocol (MCP) server. It is a thin client over the public REST API; the only credential it needs is a `REHELIOS_API_KEY` (`rh_live_…`) in the environment. It runs on Node 18+ via `npx`, with no install step.

### Why it matters for agents

An agent building or operating a product can put video live autonomously: upload a local file or import a URL, wait for transcoding, and get back an embeddable URL — in a single tool call or one CLI command. The multi-step presigned multipart upload and the ready-state polling are handled for you, so the agent does not orchestrate low-level HTTP.

### CLI

```bash
export REHELIOS_API_KEY=rh_live_...

# upload a local file, block until it is playable, print the embed URL
npx @rehelios/cli upload ./demo.mp4 --wait

# import from a public URL (e.g. AI-generated media)
npx @rehelios/cli import https://host/clip.mp4 --wait

# list, inspect, embed
npx @rehelios/cli ls --status ready
npx @rehelios/cli get <id>
npx @rehelios/cli embed <id> --iframe
```

Add `--json` to any command for machine-readable output. The installed binary is `rehelios`.

### MCP server

Run the MCP server over stdio and register it with any MCP client (Claude Desktop, Cursor, Claude Code):

```json
{
  "mcpServers": {
    "rehelios": {
      "command": "npx",
      "args": ["-y", "@rehelios/cli", "mcp"],
      "env": { "REHELIOS_API_KEY": "rh_live_..." }
    }
  }
}
```

Tools exposed to the agent:

- `rehelios_upload` — upload a local file path; returns the embed URL.
- `rehelios_import` — import from a public URL.
- `rehelios_list` — list videos with filters (status, search, collection).
- `rehelios_get` — get a video's full details.
- `rehelios_get_embed` — get the embed URL for a video id.

### Configuration

| Env var | Default |
|---|---|
| `REHELIOS_API_KEY` | — (required) |
| `REHELIOS_API_URL` | https://api.rehelios.com |
| `REHELIOS_APP_URL` | https://app.rehelios.com |

## Frequently asked questions

**What is rehelios?**
rehelios is a hosted video infrastructure platform for developers. You upload a video and rehelios transcodes it into adaptive HLS (plus optional MPEG-DASH and progressive MP4), stores it durably, and delivers it from a global CDN with signed playback, subtitles, chapters, analytics, and a REST API.

**How is rehelios priced?**
rehelios is usage-based: $0.01 per GB of storage per month and $0.005 per GB delivered, with a $1 monthly minimum. Encoding is free — there is no per-minute transcoding charge — and the player, signed playback, API, and webhooks are included.

**Is encoding really free?**
Yes. Transcoding into the adaptive bitrate ladder is included at no extra cost. You only pay for the storage your encoded renditions occupy and the bandwidth you deliver to viewers.

**What video formats does rehelios output?**
Every upload is transcoded into an adaptive HLS stream (240p to 1080p). You can also enable MPEG-DASH output and a progressive MP4 download from the same source.

**How does rehelios secure private videos?**
An edge gate authorizes every request before serving a segment, in one of two modes: a short-lived signed JWT token appended to the URL (`?token=`), or a per-org domain allowlist that authorizes by the page's Referer/Origin (Bunny-style, so the URL needs no token and never expires). Auth is cookie-free, so it works inside cross-site embeds. Original uploads are never exposed. You can also make a video public and embed it with an iframe at any time.

**Is rehelios a drop-in replacement for Bunny Stream?**
Yes. Like Bunny, you can authorize playback by domain (Referer/Origin) instead of a token: set your allowed domains and hand the player a plain, stable `playbackUrl` — no token, no expiry, no player changes. The signed-token mode is also available when you want per-viewer, expiring URLs.

**Does rehelios have an API?**
Yes. rehelios exposes a full REST API authenticated with scoped API keys, documented with OpenAPI at https://api.rehelios.com/openapi. It also sends HMAC-signed webhooks — video.ready, video.failed, and caption.ready — so you can react to events without polling.

**Can an AI agent operate rehelios?**
Yes — rehelios is agent-native. The `@rehelios/cli` npm package is both a CLI and an MCP (Model Context Protocol) server. Add `npx -y @rehelios/cli mcp` to an MCP client like Claude Desktop, Cursor, or Claude Code, set the `REHELIOS_API_KEY` env var, and the agent can upload, import, list, inspect, and embed videos through tools (`rehelios_upload`, `rehelios_import`, `rehelios_list`, `rehelios_get`, `rehelios_get_embed`). The same package works as a plain CLI: `npx @rehelios/cli upload ./file.mp4 --wait` prints a ready-to-embed URL.

**How is rehelios different from Cloudflare Stream or Bunny Stream?**
rehelios bills per gigabyte stored and delivered, the same model as Bunny Stream, rather than per minute of video like Cloudflare Stream. Encoding is free, MPEG-DASH output is available, and signed playback, the REST API, and webhooks are all included.

**Can I migrate my existing video library from S3, R2, or Bunny without re-uploading from my computer?**
Yes. Use `POST /v1/videos/import` with the public URL of each existing video file. rehelios fetches it server-side, stores it, and runs the full transcode pipeline. The `video.ready` webhook fires per video when encoding completes. This is the recommended path for bulk migrations from any CDN or object storage bucket.

**Can I embed videos on my own site?**
Yes. Public videos can be embedded with a simple iframe, and private videos can be played using a signed playback token that you generate through the API.

## Technical specifications

- **Encoding codec:** H.264 (AVC)
- **Output resolutions:** 240p, 360p, 480p, 720p, 1080p
- **Manifest types:** HLS (`.m3u8`), MPEG-DASH (`.mpd`)
- **Download format:** Progressive MP4
- **Caption formats:** VTT, SRT
- **Upload protocol:** TUS (resumable), direct PUT, URL import (`POST /v1/videos/import`)
- **Auth:** Bearer token (scoped API keys), short-lived JWT (playback)
- **Webhook signing:** HMAC-SHA256

## Links

- Home: https://rehelios.com
- App / sign up: https://app.rehelios.com
- Docs (CLI + MCP setup): https://rehelios.com/docs
- API reference (OpenAPI): https://api.rehelios.com/openapi
- npm package: https://www.npmjs.com/package/@rehelios/cli

## Positioning

rehelios is an alternative to Cloudflare Stream, Bunny Stream, and Mux for developer teams and AI agents that want per-gigabyte pricing, free encoding, signed playback, MPEG-DASH output, a developer-first REST API, and an agent-native CLI + MCP server — without a sales process or per-seat licensing.