Hyperframes Use Cases

The HeyGen API gives you the pieces — a talking avatar, background music, and sound effects. Hyperframes composites them into one video: drop the avatar clip into a designed scene, add graphics, score it, and render to a single MP4. This guide wires all four APIs into one pipeline:

Generate the avatar video

Create the talking-head clip with POST /v3/videos. Pick an engine — Avatar IV (default), Avatar V (highest fidelity), or Avatar III — then poll until it’s completed and keep the video_url.

curl -X POST "https://api.heygen.com/v3/videos" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Here are our Q2 results.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": { "type": "avatar_v" }
  }'

Poll GET /v3/videos/{video_id} until status is completed, then read video_url. See the Digital Twin guide for the full request-and-poll flow.

Find background music

Search the music catalog with a plain-language description and take the top track’s audio_url (Background music).

curl -X GET "https://api.heygen.com/v3/audio/sounds?query=upbeat%20corporate%20background&limit=1" \
  -H "x-api-key: YOUR_API_KEY"

Find sound effects

Same endpoint, with type=sound_effects — grab a whoosh for your title reveal or a chime for a stat pop (Sound effects).

curl -X GET "https://api.heygen.com/v3/audio/sounds?query=whoosh%20for%20a%20scene%20change&type=sound_effects&limit=1" \
  -H "x-api-key: YOUR_API_KEY"

Each audio_url is a short-lived pre-signed link. Feed it straight into the render step below rather than caching it.

Compose the scene in Hyperframes

Build a composition that arranges the avatar clip and audio inside a designed frame. Expose each asset URL as a composition variable so you can inject the URLs from steps 1–3 at render time — the same bundle then works for any avatar clip and any track.

index.html

<body
  data-composition-variables='{
    "avatarUrl": "",
    "musicUrl": "",
    "sfxUrl": ""
  }'
>
  <!-- The avatar clip, placed into your branded scene -->
  <video data-hf-src="avatarUrl" class="avatar"></video>

  <!-- Lower third, titles, charts — your motion graphics go here -->
  <div class="lower-third">Q2 Revenue · $1.2M</div>

  <!-- Score + one-shot sound effect, layered over the scene -->
  <audio data-hf-src="musicUrl" data-hf-volume="0.3"></audio>
  <audio data-hf-src="sfxUrl" data-hf-start="0.5"></audio>
</body>

The exact media, timing, and audio APIs live in the Hyperframes developer docs — the snippet above is illustrative. For design patterns, see the Hyperframes cookbook.

Render the finished video

Package the composition as a .zip, then submit it to POST /v3/hyperframes/renders, passing the URLs from the earlier steps as variables. HeyGen renders the composed scene — avatar, graphics, music, and SFX baked into one file.

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" },
    "format": "mp4",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "variables": {
      "avatarUrl": "https://.../avatar-video.mp4",
      "musicUrl": "https://.../background-music.wav",
      "sfxUrl": "https://.../whoosh.wav"
    },
    "title": "Q2 results — composed"
  }'

Poll GET /v3/hyperframes/renders/{render_id} until status is completed and download the final video_url. Full render options are in Hyperframes Cloud Rendering.

End-to-end example

import requests, time

API_KEY = "YOUR_API_KEY"
BASE = "https://api.heygen.com"
HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}


def poll(url, done="completed", key="status"):
    while True:
        data = requests.get(url, headers=HEADERS).json()["data"]
        if data[key] == done:
            return data
        if data[key] == "failed":
            raise RuntimeError(data.get("failure_message", "job failed"))
        time.sleep(10)


# 1. Avatar video
vid = requests.post(f"{BASE}/v3/videos", headers=HEADERS, json={
    "type": "avatar",
    "avatar_id": "YOUR_LOOK_ID",
    "script": "Here are our Q2 results.",
    "voice_id": "YOUR_VOICE_ID",
    "resolution": "1080p",
    "engine": {"type": "avatar_v"},
}).json()["data"]
avatar_url = poll(f"{BASE}/v3/videos/{vid['video_id']}")["video_url"]

# 2 + 3. Music and a sound effect (same endpoint, different type)
music_url = requests.get(
    f"{BASE}/v3/audio/sounds?query=upbeat corporate background&limit=1",
    headers=HEADERS).json()["data"][0]["audio_url"]
sfx_url = requests.get(
    f"{BASE}/v3/audio/sounds?query=whoosh for a scene change&type=sound_effects&limit=1",
    headers=HEADERS).json()["data"][0]["audio_url"]

# 4 + 5. Compose everything in Hyperframes and render
render = requests.post(f"{BASE}/v3/hyperframes/renders", headers=HEADERS, json={
    "project": {"type": "asset_id", "asset_id": "YOUR_PROJECT_ZIP_ASSET_ID"},
    "format": "mp4",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "variables": {
        "avatarUrl": avatar_url,
        "musicUrl": music_url,
        "sfxUrl": sfx_url,
    },
    "title": "Q2 results — composed",
}).json()["data"]
final = poll(f"{BASE}/v3/hyperframes/renders/{render['render_id']}")
print("Final video:", final["video_url"])

Every step here is also available through the HeyGen MCP, so an agent can run the whole avatar → audio → compose → render pipeline on its own.

Introduction to Hyperframes — what the framework is and how compositions work
Hyperframes Cloud Rendering — the full render API, parameters, and webhooks
Generate Avatar Video · Background music · Sound effects

Auth

User Info

Models

Video Generation

Video Composition

Realtime Video

Video Translation

Video Agent

Lipsync

Tools

Avatar Management

Voice Management

Asset Management

Batches

Webhook

Limits

Pricing

Socials

For Agents

Integrations

End-to-end example

​End-to-end example

​Related

End-to-end example

Related