> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes.heygen.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cloud Rendering
> Render a composition on HeyGen's hosted cloud — no local Chrome, no FFmpeg, no AWS to manage.
Render any HyperFrames composition on HeyGen's managed cloud: the CLI zips your project, uploads it, runs the render on HeyGen's infrastructure, and downloads the finished video. There's nothing to deploy and no Chrome or FFmpeg to install — you pay per credit.
```bash theme={null}
hyperframes auth login # one-time sign-in
hyperframes cloud render # zip → upload → render → download
```
```bash theme={null}
# ◆ Zipping my-video
# 42 files · 3.1 MB
# ◆ Uploading to /v3/assets
# asset_id: asst_abc123 · 1.2s
# Polling hfr_def456 every 10s …
# completed 47s
# ◆ Downloading to renders/hfr_def456.mp4
# 8.4 MB written
```
This is the zero-infra alternative to running your own renderer. If you'd rather own the compute, see [AWS Lambda](/deploy/aws-lambda), [GCP Cloud Run](/deploy/gcp-cloud-run), or the [one-click Vercel/Cloudflare templates](/guides/deploy). For local iteration during authoring, use [`hyperframes render`](/guides/rendering).
## Authenticate
Cloud rendering needs a HeyGen credential. Sign in once — the CLI stores it in `~/.heygen/credentials` (mode `0600`), and the same credential drives every `cloud` subcommand.
The default flow opens your browser for OAuth 2.0 + PKCE and captures the token on a loopback port:
```bash theme={null}
hyperframes auth login
# ✓ Signed in as you@example.com.
```
For CI or headless machines, use a long-lived API key instead:
```bash theme={null}
# Interactive hidden-input prompt
hyperframes auth login --api-key
# Or pipe a key from stdin
echo "$HEYGEN_API_KEY" | hyperframes auth login --api-key
```
```bash theme={null}
hyperframes auth status
# Shows the active credential's source, identity, and billing snapshot.
```
The credential is **shared with the [`heygen` CLI](https://github.com/heygen-com/heygen-cli)** — sign in with one and the other picks up the session. Credentials resolve in this order (first match wins):
1. `HEYGEN_API_KEY` environment variable
2. `HYPERFRAMES_API_KEY` environment variable (hyperframes alias)
3. `~/.heygen/credentials`
Point the CLI at a different backend with `HEYGEN_API_URL` (default `https://api.heygen.com`). Use `hyperframes auth refresh` to force-refresh an OAuth token before a long job; `hyperframes auth logout` clears the stored credential. For the keys voice, music, and capture use across the skills — and the fully local fallback — see [Authentication & API keys](/guides/authentication).
## How a cloud render flows
`hyperframes cloud render` runs the whole pipeline end-to-end:
```
Your machine HeyGen cloud
┌─────────────────────────┐ ┌─────────────────────────────────┐
│ zip project │ ──POST──▶│ /v3/assets │
│ (excludes .git, │ upload │ → asset_id │
│ node_modules, dist…) │ │ │
│ │ ──POST──▶│ /v3/hyperframes/renders │
│ │ submit │ → render_id (queued) │
│ │ │ Chromium + FFmpeg render │
│ poll GET /renders/{id} │ ◀────────│ queued → rendering → completed │
│ stream video to disk │ ◀────────│ signed video_url │
└─────────────────────────┘ └─────────────────────────────────┘
```
1. **Resolve the project** — a local directory (default `.`), or skip the upload with `--asset-id` / `--url`.
2. **Auto-detect the aspect ratio** from the entry HTML's `data-width`/`data-height` so you rarely set it by hand.
3. **Zip** the project (same ignore set as `hyperframes publish`).
4. **Upload** the zip to `POST /v3/assets`, yielding an `asset_id`.
5. **Submit** the render to `POST /v3/hyperframes/renders`.
6. **Poll** `GET /v3/hyperframes/renders/{id}` until it completes or fails (skip with `--no-wait`).
7. **Download** the signed video URL to disk.
## Render options
The most-used flags — see the [CLI reference](/packages/cli#hyperframes-cloud) for the full list.
| Flag | Default | Meaning |
| ---------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--fps` | `30` | Frames per second, 1–240. |
| `--quality` | `standard` | `draft`, `standard`, or `high`. |
| `--format` | `mp4` | `mp4`, `webm`, or `mov` (webm/mov carry alpha). |
| `--resolution` | `1080p` | `1080p` or `4k`. 4k is billed at 1.5×. |
| `--aspect-ratio` | auto | `16:9`, `9:16`, or `1:1`. Auto-detected from a local project's `data-width`/`data-height`; for `--asset-id`/`--url` it defaults to `16:9` unless set. |
| `--composition` / `-c` | `index.html` | Entry HTML file inside the zip. |
| `--output` / `-o` | `renders/.` | Local destination for the download. |
```bash theme={null}
# Pick a composition and an output path.
hyperframes cloud render . \
--composition compositions/intro.html \
--output ./renders/intro.mp4
# Higher quality at 60fps.
hyperframes cloud render --quality high --fps 60
```
`--resolution 4k` can't be combined with `--format webm` or `--format mov`. The 4k supersampling path runs through the screenshot capture pipeline, which has no alpha channel. Render 4k as `mp4`, or render alpha at the composition's native resolution.
## Templates and variables
Cloud rendering supports [variables](/concepts/variables) — the same mechanism that powers templates everywhere else in HyperFrames. Declare `data-composition-variables` on your composition, then fill them at render time:
```bash theme={null}
# Inline JSON
hyperframes cloud render --variables '{"title":"Q4 Recap","theme":"dark"}'
# From a file
hyperframes cloud render --variables-file ./vars.json
# Fail fast on undeclared keys or wrong types
hyperframes cloud render --variables '{"title":"Q4 Recap"}' --strict-variables
```
For a **local project**, the CLI validates your `--variables` against the composition's declared schema *before* uploading. For `--asset-id` / `--url` the schema lives server-side, so mismatches surface as a `hyperframes_project_invalid` API error.
The idiomatic template workflow is **upload once, re-render many**: render a local project to get its `asset_id`, then submit new renders against that same asset with different variables — no re-zip, no re-upload.
```bash theme={null}
# 1. Upload + render once; note the asset_id printed during upload.
hyperframes cloud render ./card-template
# 2. Re-render the same asset with new values (skips zip + upload).
hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Linus"}'
```
For high-volume personalized batches, the bring-your-own-AWS path adds a JSONL fan-out — see [Templates on Lambda](/deploy/templates-on-lambda).
## Fire-and-forget and webhooks
By default the CLI blocks, polls, and downloads. Pass `--no-wait` to submit and exit with just the `render_id`, and `--callback-url` to get an HTTPS webhook when the render terminates. The webhook fires whether or not the CLI is still polling, so combine them for true fire-and-forget:
```bash theme={null}
hyperframes cloud render --callback-url https://example.com/hf-hook --no-wait
# ✓ Submitted hfr_def456
# Poll with: hyperframes cloud get hfr_def456
```
| Flag | Meaning |
| ----------------- | --------------------------------------------------- |
| `--no-wait` | Submit and exit immediately; print the `render_id`. |
| `--callback-url` | HTTPS webhook fired when the render terminates. |
| `--callback-id` | Opaque tracking ID echoed in webhook payloads. |
| `--poll-interval` | Poll cadence in seconds (default `10`). |
| `--max-wait` | Max poll duration in minutes (default `60`). |
## Managing renders
```bash theme={null}
hyperframes cloud list # recent renders (--limit, --token, --all)
hyperframes cloud get hfr_def456 # full detail + short-lived signed video_url
hyperframes cloud delete hfr_def456 # soft-delete (--no-confirm to skip the prompt)
```
`video_url` and `thumbnail_url` are short-lived presigned URLs — re-fetch with `cloud get` rather than caching them.
## Safe retries
The CLI transparently retries on a `401 Unauthorized` by force-refreshing the OAuth token and replaying the request. That's harmless for reads, but the zip upload (`POST /v3/assets`) is **not** idempotent on its own — a blind retry would create a duplicate asset and bill the workspace twice. Pass `--idempotency-key` so retries are safe:
```bash theme={null}
hyperframes cloud render . --idempotency-key "$(uuidgen)"
```
The key is forwarded to both the upload and submit calls; the server scopes idempotency per-endpoint, so reusing one value across both steps is safe. Use any opaque string in `[A-Za-z0-9_:.-]` (1–255 chars).
## Cloud vs. Lambda vs. local
* **`hyperframes render`** (local) — fastest iteration loop; use while authoring. See [Rendering](/guides/rendering).
* **`hyperframes cloud render`** — zero-infra; HeyGen runs the render and you pay per credit. Use when you don't want to manage Chrome/FFmpeg/AWS.
* **`hyperframes lambda render`** — bring-your-own-AWS distributed rendering with chunked parallelism. Use when you've already invested in AWS. See [AWS Lambda](/deploy/aws-lambda).
## Next steps
Declare and fill template slots in a composition
High-volume personalized renders on your own AWS
Render locally or in Docker during authoring
Every `cloud` and `auth` flag in detail