Skip to main content
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.
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.
HyperFrames uses its own public OAuth client and stores credentials in ~/.hyperframes/credentials (mode 0600). Sign in again after upgrading from the shared HeyGen login. The separate heygen CLI keeps its own login in ~/.heygen; HyperFrames does not move or delete it. A signed-in HyperFrames session wins over HEYGEN_API_KEY in the environment. The environment key is used only when no session is signed in, when HeyGen refuses to refresh the session, or when a host app routes calls through its own gateway. An expired session never selects a saved API key instead. An API key, from the environment or auth login --api-key, selects API-key billing. auth status verifies identity. For a dedicated HyperFrames OAuth login it reports the billing product, but the HyperFrames balance is unavailable here: /v3/users/me returns generic HeyGen account billing fields. Those raw fields remain in JSON and are not presented as the HyperFrames balance. Host-injected or custom-client OAuth is reported as an unverified billing product.
No account is needed to try HyperFrames locally. With no credential, voice can use Kokoro and music can use MusicGen — see Working offline.

​
How the HeyGen credential resolves

The bundled audio scripts use the HeyGen credential for hosted TTS and music / sound retrieval. It resolves first-match-wins:
  1. HEYGEN_API_BASE with HEYGEN_API_KEY — a host app’s own gateway, set by the app that started the workflow
  2. HEYGEN_ACCESS_TOKEN — an OAuth token a host app injects
  3. The session hyperframes auth login saved in ~/.hyperframes/credentials, while it is unexpired
  4. HEYGEN_API_KEY — environment variable
  5. HYPERFRAMES_API_KEY — alias, for parity with other tools
  6. An API key saved in ~/.hyperframes/credentials by hyperframes auth login --api-key
A nearby project .env can supply the keys, but never HEYGEN_API_BASE. Point at a different config directory with HYPERFRAMES_CONFIG_DIR. The scripts can’t refresh a session; the hyperframes CLI’s own commands use the same order and refresh an expired session first. See the CLI reference. When media-use invokes the separate heygen executable, it supplies an isolated temporary credential containing the selected access token. That helper cannot refresh a HyperFrames grant or pick up another HeyGen login.

​
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. 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. For Gemini narration, explicitly ask your agent to use Gemini TTS. The shared audio workflow supports 3.8 Flash and Flash-Lite, 3.1 Flash Preview, and 2.5 Pro and Flash Preview. Gemini remains an explicit choice; configuring credentials does not change the automatic voice-provider order above. Choose one authentication method:
  • API key: set GEMINI_API_KEY or GOOGLE_API_KEY in your environment or project .env. This path needs no Python dependencies.
  • Service account: install google-auth and requests in your Python 3 environment, then set GOOGLE_APPLICATION_CREDENTIALS to the absolute path of your service-account JSON file. Alternatively, inject the JSON through GCS_CREDS from your secret manager. Set GOOGLE_CLOUD_PROJECT to the quota project when it differs from the service account’s project.
Credentials resolve in that order: Gemini key, Google key, service-account file, then JSON environment variable. Unset API keys when choosing service-account OAuth. The helper obtains a fresh token for each generation using the generative-language.retriever scope. Keys and tokens are never placed in compositions or saved audio metadata. Both methods call the Gemini Developer Interactions API. Your project needs access to that API and the requested model. Cloud Text-to-Speech and Vertex AI have separate model availability. This helper accepts service-account JSON, not user ADC files or metadata-server credentials. See Gemini voiceover.
npx hyperframes tts itself is the local Kokoro CLI. Hosted HeyGen and ElevenLabs and Gemini 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