> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Authentication & API keys
> Sign in to HeyGen and understand how agent workflows choose voice, music, sound, and optional capture-description providers.
You can create and render locally without an account. Voice and music can fall
back to local engines when no provider key is available. Sign in when you want
HeyGen voice and music, managed cloud rendering, hosted MCP, or ownership of a
published project that you can update later.
## Sign in
Signing in is the same OAuth step as creating an account — new users land on the sign-up screen.
The default flow opens your browser for OAuth and captures the token on a loopback port:
```bash theme={null}
npx hyperframes auth login
# ✓ Signed in.
```
For CI or headless machines, save a long-lived API key instead:
```bash theme={null}
npx hyperframes auth login --api-key # hidden-input prompt
echo "$HEYGEN_API_KEY" | npx hyperframes auth login --api-key # from stdin
```
```bash theme={null}
npx hyperframes auth status
```
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](https://github.com/heygen-com/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 is needed to try HyperFrames locally. With no credential, voice can
use **Kokoro** and music can use **MusicGen** — see [Working
offline](#working-offline).
## How the HeyGen credential resolves
Bundled media workflows use the HeyGen credential for hosted TTS and music /
sound 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`.
## Providers used by agent workflows
After the workflow's sign-in preflight, each media capability uses the first
available provider in its order. Voice, music, and sound have offline
fallbacks; capture descriptions are optional and are skipped when no supported
vision key is available.
| Capability | Provider order | Key(s) — first match wins | Local dependency |
| ------------------------ | --------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Voice (TTS)** | HeyGen → ElevenLabs → Kokoro | `HEYGEN_API_KEY` → `HYPERFRAMES_API_KEY` → `~/.heygen` · then `ELEVENLABS_API_KEY` | Kokoro: `pip install kokoro-onnx soundfile` |
| **Music (BGM)** | HeyGen library → Lyria → MusicGen | HeyGen credential (above) · then `GEMINI_API_KEY` → `GOOGLE_API_KEY` | MusicGen: `pip install transformers torch soundfile numpy` |
| **Sound effects** | HeyGen library → bundled library | HeyGen credential (above) | bundled — no deps |
| **Capture descriptions** | OpenRouter → Gemini | `OPENROUTER_API_KEY` → `GEMINI_API_KEY` | None; optional for [website capture](/guides/product-launch-video) |
Run `npx hyperframes doctor` to check which local dependencies are installed.
The media workflows run `hyperframes auth status` before generation and tell
you which path they will use.
`npx hyperframes tts` itself is the local Kokoro CLI. Hosted HeyGen and
ElevenLabs voices are selected by the bundled media workflow helpers, not by
that command.
## Working offline
No key configured is a normal state for local work. After their dependencies
and model files are installed, these fallbacks run locally:
* **Voice** — Kokoro-82M (54 voices), with Whisper for word-level caption alignment.
* **Music** — MusicGen (`facebook/musicgen-small`).
* **Sound effects** — a bundled library.
Local engines do not call a hosted generation API after setup. Their first use
may download model files. HeyGen provides managed voices and a produced music
library; sign in when you want those services or cloud rendering.
## Publishing without an account
`npx hyperframes publish` works while signed out. It uploads the project and
prints a URL containing a claim token. Open that URL and authenticate in the web
app to claim the project.
Sign in with `npx hyperframes auth login` before publishing when you want the CLI
to own the project immediately, update the same URL with `--update`, or publish
to a shared space with `--space`.
## Environment variables
| Variable | Used for |
| ----------------------------------- | ------------------------------------------------------------------ |
| `HEYGEN_API_KEY` | HeyGen credential — voice + music/SFX retrieval. Highest priority. |
| `HYPERFRAMES_API_KEY` | Alias for `HEYGEN_API_KEY`. |
| `HEYGEN_API_URL` | API base URL (default `https://api.heygen.com`). |
| `HEYGEN_CONFIG_DIR` | Credentials directory (default `~/.heygen`). |
| `ELEVENLABS_API_KEY` | ElevenLabs TTS, used when no HeyGen credential is present. |
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Lyria music generation (and capture descriptions). |
| `OPENROUTER_API_KEY` | Capture descriptions; takes priority over Gemini for that step. |
See the [`hyperframes auth`](/packages/cli#hyperframes-auth) command reference for subcommand details, and [Cloud rendering](/deploy/cloud) for using the same credential to render in HeyGen's cloud.