Skip to main content
HyperFrames uses a HeyGen credential for premium voiceover (TTS) and the music / sound-effects library. Other providers are optional, and everything runs without any key — voice and music fall back to fully local engines. This page covers signing in, the keys each capability uses, and the order they resolve.

​
Sign in

Signing in is the same OAuth step as creating an account — new users land on the sign-up screen.
1

Sign in

The default flow opens your browser for OAuth and captures the token on a loopback port:
For CI or headless machines, save a long-lived API key instead:
2

Confirm what's configured

Shows the active credential’s source and verified identity, and — when you’re signed out — which local engines voice and music will use. Add --json for { configured, recommended_action, offline_engines } in scripts.
The credential lives in ~/.heygen/credentials (mode 0600) — no per-repo .env to manage. Browser OAuth is a hyperframes auth login feature. The separate heygen CLI (its own install — there’s no npx heygen) is API-key-only, so heygen auth login just stores a key you paste. Both read the same ~/.heygen/credentials, so signing in with one carries to the other.
No account needed to try HyperFrames. With no credential, voice uses Kokoro and music uses MusicGen, both fully local and offline — see Working offline.

​
How credentials resolve

The HeyGen credential drives TTS and music / SFX retrieval. It resolves first-match-wins:
  1. HEYGEN_API_KEY — environment variable
  2. HYPERFRAMES_API_KEY — alias, for parity with other tools
  3. ~/.heygen/credentials — written by hyperframes auth login (or heygen auth login)
Point at a different config directory with HEYGEN_CONFIG_DIR, or a different backend with HEYGEN_API_URL.

​
Keys by capability

Each capability picks the first available provider in order; the last is always a local engine that needs no key. Cloud providers below the HeyGen line need their own key and a local Python dependency. Run npx hyperframes doctor to check which local dependencies are installed. The media skills also run hyperframes auth status as a preflight before generating, so you always know whether a run will use HeyGen or a local engine before it starts.

​
Working offline

No key configured is a normal state, not an error. The workflow runs entirely on local models:
  • Voice — Kokoro-82M (54 voices), with Whisper for word-level caption alignment.
  • Music — MusicGen (facebook/musicgen-small).
  • Sound effects — a bundled library.
Local engines are free and offline; HeyGen gives higher-quality voices and a professionally produced music library. Sign in any time to switch a project from local to HeyGen.

​
Environment variables

See the hyperframes auth command reference for subcommand details, and Cloud rendering for using the same credential to render in HeyGen’s cloud.