Jonathon's AI Wiki

HyperFrames Media Library (/media-use) — 10k Tracks, 75k Images, Free with a HeyGen Login

6 min read

Source: HeyGen launch tweet, 2026-07-17 (“We gave HyperFrames a media library — 10k+ tracks, 75k+ images, sfx, logos, free with a HeyGen login. Plus access to our generative models. Assets save to your machine…”) · skills/media-use/SKILL.md · releases v0.7.61 · MCP guide · HeyGen remote MCP

On 2026-07-17 (framework v0.7.61) HeyGen gave HyperFrames a media library reached through the /media-use skill: 10k+ music tracks, 75k+ images, sound effects, and logos, plus access to HeyGen’s generative models (voice/TTS, image, and — new this release — avatar-video). The catalog is HeyGen-hosted; the client that queries it is open-source; downloaded assets are frozen to the local machine so the next project skips the search. The headline “free with a HeyGen login” is precise and load-bearing: free applies to the OAuth login path, not the API-key path.

This article resolves a common conflation — there are three login-gated surfaces, and the launch is about the middle one. It also corrects the older provider-chain understanding captured in SDK & Authentication (which had no image library and framed sign-in as a “premium” upgrade).

Key Takeaways

  • OSS client, hosted catalog. The media-use skill + the separate heygen CLI (the client) are open/free and shell out to HeyGen over the network (heygen audio sounds list, heygen asset search, both tagged X-HeyGen-Client-Source: media-use). The catalog itself (10k tracks / 75k images / SFX / logos) lives server-side, behind a HeyGen login — the repo ships the query client and the freeze/cache layer, never the assets.
  • “Free” = the OAuth session, not the API key. heygen auth login --oauth unlocks a free subscription allowance for bgm/SFX/image/icon catalog search + TTS voice; heygen auth login --api-key runs the same calls but bills API credits (the paid plan_credit pool avatar renders draw on). This is the single most important operational fact.
  • CLI floor raised to v0.3.0. The launch requires heygen ≥ v0.3.0 uniformly (was ≥ v0.1.6 for the pre-launch asset search). Install unchanged: curl -fsSL https://static.heygen.ai/cli/install.sh | bash.
  • Generative models are new here. A June-2026 install had only search providers (a provider.generate hook existed but was unimplemented). The launch wires generation: voice/TTS (HeyGen, free-usage), image (catalog search → local mflux/FLUX or a codex upsell on miss), video — new in v0.7.61 — resolve --type video → HeyGen avatar-video (metered free allowance, confirms before spending) with a local LTX fallback, and music (retrieve | generate). All via the skill’s resolve verb, not an MCP tool.
  • Assets cache locally, twice. Downloads freeze to the project’s .media/ (manifest .media/manifest.jsonl + agent-readable .media/index.md) and promote to a global content-addressed ~/.media/ (SHA-256), so a repeat prompt hits cache with no provider call — the tweet’s “next project skips the search.”
  • Not the MCP connector. The credit-metered “HyperFrames by HeyGen” remote MCP (cloud authoring/rendering inside an LLM chat) is a different surface and does not reach this media library or the generative models — it can only reference assets already uploaded to HeyGen’s web UI.

The three login-gated surfaces (don’t conflate them)

#SurfaceWhat it isAuthCostThis launch?
1OSS framework — hyperframes binary + media-use skill codeApache-2.0, renders HTML→MP4 locally; ships the query client + the .media//~/.media/ freeze-cache layer, not the catalognonefreeships the client only
2heygen CLI + HeyGen-hosted catalogThe 10k tracks / 75k images / SFX / logos + generative models; catalog is server-sideheygen auth login --oauth (API key = billed)free on OAuth✅ this is the tweet
3”HyperFrames by HeyGen” remote MCP — mcp.heygen.com/mcp/hyperframesCloud authoring + rendering in an LLM chat; 6 tools (compose, render_video, get_credits, …)OAuth connectorplan-credit metered❌ — and cannot reach the library

Surface 3 is documented in the launch-video playbook and the skills catalog; the guide states plainly that “the MCP gives you instant authoring with cloud rendering… use the CLI if you need local rendering,” and its asset model is “reference assets you’ve already uploaded to HeyGen” — i.e. no browsable catalog.

Auth & cost — the OAuth-vs-API-key split

Verbatim from the current skill’s Setup section:

heygen auth login --oauth    # OAuth = free subscription credits; --api-key bills API credits
# unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS voice, and avatar videos
# media-use requires heygen >= v0.3.0 uniformly
  • Free on OAuth: bgm / SFX / image / icon catalog search + download, and TTS (voice).
  • Metered exception: avatar video generation is “flagged paid (metered free allowance),” so an agent-initiated resolve --type video confirms before spending (the skill’s “cost rule”).
  • API-key path bills: authenticating with --api-key routes the same calls through paid API credits. The heygen CLI’s API-key mode is the same HeyGen credential system as the avatar-video API (HEYGEN_API_KEY, api.heygen.com) — the new thing is that OAuth grants a separate free allowance the API key does not.

Practical corollary for any pipeline already holding a HEYGEN_API_KEY for avatar renders: pointing media-use at that key does not get you the free library — it bills. The free library requires a distinct OAuth browser sign-in.

Generative models (launch-day addition)

TypePath on resolveFree?
Voice / TTSHeyGen TTS (free-usage); local Kokoro fallbackfree
ImageHeyGen asset search first → local mflux (FLUX) / codex image_gen upsell on misssearch free; local gen free/offline
Video (new v0.7.61)HeyGen avatar-video (free-usage, metered) → local LTX fallbackmetered free allowance
Music / BGMbgm.mode = retrieve | generate | noneretrieve free

The changelog line: “Media Use: Add video generation (HeyGen avatar-video + local LTX fallback)” (v0.7.61). Generation is invoked through the same resolve verb the search providers use — there is no separate heygen generate command and no MCP dependency.

Assets save to your machine

  • Project cache: .media/<type>/ with manifest.jsonl (machine SSOT, one JSON record per line) + index.md (agent-readable table). resolve --adopt bulk-imports an existing assets/ folder into the manifest with real ffprobe durations/dimensions.
  • Global cache: ~/.media/ — content-addressed by SHA-256, cross-project. A repeat prompt hits it with no re-download and no provider call.

What this corrects in the prior wiki record

SDK & Authentication documented the pre-launch provider chain as Music = HeyGen library → Lyria → MusicGen; SFX = HeyGen library → bundled, with no image library and sign-in framed as a “premium media” upgrade. Post-launch: (1) there is now a first-class image/icon catalog (heygen asset search, 75k+ vectors); (2) the catalog is free on OAuth, not merely “premium”; (3) generative models (incl. new avatar-video) are wired into resolve.

Open Questions

  • Exact free-allowance quotas — how many free avatar-video seconds per period, and whether a pure zero-generation catalog lookup decrements anything under an API key. The skill states the API-key path “bills API credits” only in general terms.
  • The image generator’s identity — secondary coverage references a HeyGen image model (“Image N”) for people/persona images; unverified against primary docs. ^[inferred — the skill exposes image generation on miss but does not name the hosted model]
  • Catalog counts — one secondary blog cited “100,000 background tracks”; the canonical skill figures are 10k+ tracks / 75k+ images. Treat the larger number as unverified.
  • Free-tier durability — whether the OAuth free allowance persists or is a launch-window promotion (cf. the Fable 5 free-then-metered pattern in Fable 5).

Graph View

Backlinks