> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hyperframes Cloud Rendering

> Render programmatic, code-driven video with the HeyGen Hyperframes API. Upload an HTML project bundle, inject runtime variables, and HeyGen renders it to MP4, WebM, or MOV.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-5.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=422da140ece4b799d490f85bb2013ca5)

Hyperframes turns a self-contained HTML/CSS/JS project into a rendered video. You package your composition as a `.zip`, upload it, and HeyGen runs it through a headless renderer — ideal for motion graphics, data-driven visuals, and templated pipelines. For worked examples, see the [Hyperframes cookbook](https://heygen-1fa696a7.mintlify.site/motion-graphics).

If you work from a terminal, [`hyperframes cloud render`](https://hyperframes.heygen.com/deploy/cloud) in the Hyperframes CLI wraps this entire flow — it zips your project, uploads it, submits the render, polls, and downloads the finished video in one command. This page documents the underlying API so you can build the same pipeline into your own application.

## Prerequisites

> [!TIP]
>
> A project `.zip` containing an `index.html` at the root (or at the path you set in `composition`), plus any CSS, JS, fonts, and assets it needs. The bundle must render standalone in a browser.

> [!TIP]
>
> The zip available as a `url`, an uploaded `asset_id`, or `base64`. Use [Assets](https://heygen-1fa696a7.mintlify.site/assets.md) to upload a file and get an `asset_id`.

When zipping, include only what the composition needs — leave out `.git`, `node_modules`, and build output like `dist`. A lean bundle uploads faster, and `asset_id` uploads ([direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md), up to 1 GiB) accept larger projects than the `url` and `base64` caps (see [`hyperframes_project_too_large`](https://heygen-1fa696a7.mintlify.site/docs/error-codes#hyperframes-project-too-large)).

## How a render flows

A render is three API calls end to end — upload the bundle, submit the render, then poll (or [take a webhook](#using-webhooks-instead-of-polling)) until the video is ready:

```
 Your app                              HeyGen cloud
┌─────────────────────────┐          ┌─────────────────────────────────┐
│ zip the project         │ ──POST──▶│ /v3/assets/direct-uploads       │
│                         │  upload  │  → asset_id                     │
│                         │          │                                 │
│                         │ ──POST──▶│ /v3/hyperframes/renders         │
│                         │  submit  │  → render_id (queued)           │
│                         │          │  Chromium + FFmpeg render       │
│ poll GET /renders/{id}  │ ◀────────│  queued → rendering → completed │
│ download the video      │ ◀────────│  presigned video_url            │
└─────────────────────────┘          └─────────────────────────────────┘
```

1. **Upload** the project zip with [direct upload](https://heygen-1fa696a7.mintlify.site/docs/direct-upload.md) (`POST /v3/assets/direct-uploads` with `content_type: "application/zip"`, up to 1 GiB) and note the `asset_id`. (For small or already-hosted bundles, skip this step and pass the project as `url` or `base64` instead.)
2. **Submit** the render to `POST /v3/hyperframes/renders`, which returns a `render_id` immediately.
3. **Poll** `GET /v3/hyperframes/renders/{render_id}` until the status is `completed`, then download the video from the presigned `video_url`.

The sections below walk through each call.

## Step 1 — Build your composition

Author an HTML page that renders your scene. Hyperframes compositions are standard, self-contained web pages — for the composition framework, component APIs, and local preview and render tooling, see the [Hyperframes developer docs](https://hyperframes.heygen.com/packages/core). To explore, remix, and learn from community-built compositions, browse the [Community Playground](https://www.hyperframes.dev).

To make a render data-driven, read values from `data-composition-variables` on the document — HeyGen overrides these with the `variables` object you send at render time, so one bundle can produce many videos (see [Upload once, render many](#upload-once-render-many) below). The renderer validates the bundle when the render starts; a zip without a usable entry file fails with [`hyperframes_project_invalid`](https://heygen-1fa696a7.mintlify.site/docs/error-codes#hyperframes-project-invalid), so preview the project locally (or run it through the Hyperframes CLI) before submitting.

## Step 2 — Create a render

[`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/create-hyperframes-render) with your project bundle. The call returns `202 Accepted` with a `render_id`. The reference lists every option and its default; `fps` runs 1–240, `title` takes up to 500 characters and `callback_id` up to 256.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" },
    "fps": 30,
    "quality": "standard",
    "format": "mp4",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "composition": "index.html",
    "variables": { "headline": "Q2 Revenue", "value": "$1.2M" },
    "title": "Q2 revenue motion graphic"
  }'
```

> [!NOTE]
>
> `webm` and `mov` carry an alpha channel for transparent overlays. Render `4k` as `mp4`; the 4k supersampling pipeline produces opaque frames. For transparent output, render `webm` or `mov` at `1080p`.

## Step 3 — Poll for completion

Poll [`GET /v3/hyperframes/renders/{render_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-hyperframes-render) while `status` moves from `queued` to `rendering`, until it is `completed` (or `failed`, with the reason in `failure_message`).

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/hyperframes/renders/YOUR_RENDER_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

A completed render returns the full `HyperframesRenderDetail`, including `video_url`, `thumbnail_url`, `duration`, and the settings the render used.

> [!NOTE]
>
> `video_url` and `thumbnail_url` are short-lived presigned URLs. Download the video promptly, and when you need a fresh link later, re-fetch the render with `GET /v3/hyperframes/renders/{render_id}` rather than storing the URL.

## Upload once, render many

The idiomatic template workflow: upload the project zip to [Assets](https://heygen-1fa696a7.mintlify.site/assets.md) once, then submit as many renders as you need against the same `asset_id`, each with different `variables`, with no re-zip or re-upload:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" },
    "variables": { "name": "Ada", "theme": "dark" }
  }'
```

Declare the variables (and their types) in the composition's `data-composition-variables`; the renderer validates the `variables` you send against that schema when the render runs.

## Managing renders

List your renders (paginated) with [`GET /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/reference/list-hyperframes-renders), or remove one with [`DELETE /v3/hyperframes/renders/{render_id}`](https://heygen-1fa696a7.mintlify.site/reference/delete-hyperframes-render):

```bash theme={null}
curl -X GET "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY"

curl -X DELETE "https://api.heygen.com/v3/hyperframes/renders/YOUR_RENDER_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

## Safe retries

Both `POST /v3/assets` and `POST /v3/hyperframes/renders` accept an `Idempotency-Key` header, so a network failure or timeout never leaves you guessing whether the upload or render went through — retry with the same key and the API replays the original response instead of creating (and billing) a duplicate:

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/hyperframes/renders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ "project": { "type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID" } }'
```

Keys are 1–255 characters from `[A-Za-z0-9_:.-]` — a UUID is a safe default. Replays work for 24 hours, and a retry that arrives while the original is still processing gets a `409` [`request_in_progress`](https://heygen-1fa696a7.mintlify.site/docs/error-codes#request-in-progress). Idempotency is scoped per endpoint, so reusing one key for an upload and its follow-up render is safe.

## Using webhooks instead of polling

Pass a `callback_url` (and optionally a `callback_id` to correlate the response) when you submit the render. HeyGen posts to it whether or not anything is polling, so you can submit the render and walk away — true fire-and-forget. Register an endpoint via `POST /v3/webhooks/endpoints` and subscribe to the `hyperframes_video.success` and `hyperframes_video.fail` events described in [Webhook Events](https://heygen-1fa696a7.mintlify.site/docs/webhook-events.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.