> ## 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 Use Cases

> Combine a HeyGen avatar video with background music, sound effects, and Hyperframes graphics into one finished, produced video — all through the HeyGen API.

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

The HeyGen API gives you the pieces — a talking [avatar](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md), [background music](https://heygen-1fa696a7.mintlify.site/background-music.md), and [sound effects](https://heygen-1fa696a7.mintlify.site/sound-effects.md). **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:

**1. Generate the avatar video**

Create the talking-head clip with [`POST /v3/videos`](https://heygen-1fa696a7.mintlify.site/reference/create-video). This example uses [Avatar 6](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md); [Avatar V](https://heygen-1fa696a7.mintlify.site/avatar-v.md), [Avatar IV](https://heygen-1fa696a7.mintlify.site/avatar-iv.md) (the default when `engine` is omitted) and [Avatar III](https://heygen-1fa696a7.mintlify.site/avatar-iii.md) also work.

```bash theme={null}
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": "heygen-avatar-6" }
  }'
```

Poll `GET /v3/videos/{video_id}` until `status` is `completed`, then read `video_url`. See the [Digital Twin guide](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md) for the full request-and-poll flow.

**2. Find background music**

Search the music catalog with a plain-language description and take the top track's `audio_url` ([Background music](https://heygen-1fa696a7.mintlify.site/background-music.md)).

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

**3. 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](https://heygen-1fa696a7.mintlify.site/sound-effects.md)).

```bash theme={null}
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"
```

> [!NOTE]
>
> Each `audio_url` is a short-lived pre-signed link. Feed it straight into the render step below rather than caching it.

**4. 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](https://heygen-1fa696a7.mintlify.site/hyperframes-overview.md#core-concepts) 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.

```html index.html theme={null}
<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>
```

> [!NOTE]
>
> The exact media, timing, and audio APIs live in the [Hyperframes developer docs](https://hyperframes.heygen.com/packages/core) — the snippet above is illustrative. For design patterns, see the [Hyperframes cookbook](https://heygen-1fa696a7.mintlify.site/motion-graphics).

**5. Render the finished video**

Package the composition as a `.zip`, then submit it to [`POST /v3/hyperframes/renders`](https://heygen-1fa696a7.mintlify.site/hyperframes), passing the URLs from the earlier steps as `variables`. HeyGen renders the composed scene — avatar, graphics, music, and SFX baked into one file.

```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" },
    "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](https://heygen-1fa696a7.mintlify.site/hyperframes.md).

> [!TIP]
>
> Every step here is also available through the [HeyGen MCP](https://heygen-1fa696a7.mintlify.site/mcp/overview.md), so an agent can run the whole avatar → audio → compose → render pipeline on its own.

## Related

* [Introduction to Hyperframes](https://heygen-1fa696a7.mintlify.site/hyperframes-overview.md) — what the framework is and how compositions work
* [Hyperframes Cloud Rendering](https://heygen-1fa696a7.mintlify.site/hyperframes.md) — the full render API, parameters, and webhooks
* [Generate Avatar Video](https://heygen-1fa696a7.mintlify.site/generate-avatar-video.md) · [Background music](https://heygen-1fa696a7.mintlify.site/background-music.md) · [Sound effects](https://heygen-1fa696a7.mintlify.site/sound-effects.md)


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