mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(studio): dev Studio renders apply the received-project rule for outside files The Vite Studio adapter started every render with files from outside the project allowed. It now asks the CLI's outsideAssetsAllowed, the same check the CLI's embedded Studio, hyperframes render and benchmark use. A project whose received-files record lists code files, or cannot be read, renders without files from outside the project, and the reason prints with a [studio] prefix. The adapter loads the rule from the CLI source through the dev server, as it already does for background removal. It runs only from a source checkout, so studio takes no package dependency on the CLI. * fix(cli): a received project's .env provider key never replaces your own credential A received project's .env could set OPENROUTER_API_KEY, GEMINI_API_KEY, GOOGLE_API_KEY or Vertex settings that outranked a vision or Gemini credential the person set in the shell, so capture, snapshot describe and media-use speech and music could send content to another account. After the CLI and capture load a project .env, each provider key it set is unset when that .env came with a received project (a received-files record lists it, or a record cannot be read) and the person has their own credential for a competing provider. One stderr line names the key, the .env file and the credential used instead. A person's own project .env keeps its keys and its current precedence, so an OPENROUTER_API_KEY in a project .env still wins over a Gemini key in the shell, as the docs describe. Voice needs no change: the person's HeyGen credential already ranks above ElevenLabs. * fix(cli,media-use): media-use scripts apply the received .env rule, ElevenLabs included The media-use audio scripts read the project .env again, so a Gemini key the CLI had left out came back. They now apply the same rule after loading: a key from a received project's .env gives way to the person's own credential for a competing provider. GEMINI_API_KEY and GOOGLE_API_KEY give way to the person's Gemini key or service account. ELEVENLABS_API_KEY gives way to the person's HeyGen sign-in, saved key or shell key. A dropped key gets one stderr line that names the file and the credential used instead. A received ElevenLabs key that is still used, because the person has no competing credential, gets one stderr line naming the .env before speech starts. hyperframes media-use tells the engine which keys it took from a project .env (HYPERFRAMES_PROJECT_ENV_ORIGINS), so a key the CLI loaded is not mistaken for the shell's. When the project's folders are too many to scan for received-files records, the CLI's note now says the project's origin could not be checked, instead of calling it a received project. * refactor(studio): check the shape of the CLI's outside-files rule before calling it The Vite adapter loads outsideAssetsAllowed from the CLI source at run time. It now checks that the export is a function and treats only a true result as allowed, instead of casting the module's export. * docs(auth): a received project's ElevenLabs key gives way to your HeyGen credential * test(studio): load the received-project rule before render waits start
166 lines
9.9 KiB
Plaintext
166 lines
9.9 KiB
Plaintext
---
|
|
title: Authentication & API keys
|
|
description: "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.
|
|
|
|
<Steps>
|
|
<Step title="Sign in">
|
|
The default flow opens your browser for OAuth and captures the token on a loopback port:
|
|
|
|
```bash
|
|
npx hyperframes auth login
|
|
# ✓ Signed in.
|
|
```
|
|
|
|
For CI or headless machines, save a long-lived API key instead:
|
|
|
|
```bash
|
|
npx hyperframes auth login --api-key # hidden-input prompt
|
|
echo "$HEYGEN_API_KEY" | npx hyperframes auth login --api-key # from stdin
|
|
```
|
|
</Step>
|
|
<Step title="Confirm what's configured">
|
|
```bash
|
|
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.
|
|
</Step>
|
|
</Steps>
|
|
|
|
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](https://github.com/heygen-com/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. A key from the project `.env` is used only when no session or API key is saved and the environment sets none, and the CLI names that `.env` file on stderr when it uses one. 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.
|
|
|
|
<Tip>
|
|
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).
|
|
</Tip>
|
|
|
|
## 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`
|
|
7. A key from a nearby project `.env`, only when nothing is saved
|
|
|
|
A nearby project `.env` can supply the keys, but never `HEYGEN_API_BASE`. Its key never replaces a saved
|
|
session or API key, including an expired session, and the scripts name the `.env` file on stderr when they use it. 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](/packages/cli). 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.
|
|
|
|
| Capability | Provider order | Key(s) — first match wins | Local dependency |
|
|
|------------|----------------|---------------------------|------------------|
|
|
| **Voice (TTS)** | HeyGen → ElevenLabs → Kokoro | HeyGen credential (above) · 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.
|
|
|
|
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](/prompting/media-and-audio#gemini-voiceover).
|
|
|
|
<Note>
|
|
`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.
|
|
</Note>
|
|
|
|
## 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. |
|
|
| `HYPERFRAMES_API_KEY` | Alias for `HEYGEN_API_KEY`. |
|
|
| `HEYGEN_ACCESS_TOKEN` | OAuth token a host app injects; never refreshed or saved. |
|
|
| `HEYGEN_API_BASE` | A host app's gateway for media workflows; never read from a project `.env`. |
|
|
| `HEYGEN_API_URL` | API base URL for `hyperframes` CLI commands (default `https://api.heygen.com`). |
|
|
| `HYPERFRAMES_CONFIG_DIR` | HyperFrames settings root: credentials, telemetry and update settings, project links (default `~/.hyperframes`). |
|
|
| `HYPERFRAMES_ENV` | `prod` (default) or `dev`; `dev` keeps credentials in a separate `dev/` directory under the root. Hosts and the OAuth client id come from `HEYGEN_API_URL`, `HYPERFRAMES_OAUTH_*` and `HYPERFRAMES_PUBLISHED_PROJECTS_API_URL`. |
|
|
| `HYPERFRAMES_OAUTH_CLIENT_ID` | Override the public client ID for a controlled OAuth environment. |
|
|
| `ELEVENLABS_API_KEY` | ElevenLabs TTS, used when no HeyGen credential is present. A key from a received project's `.env` is never used next to your own HeyGen credential, and a note names the file when it is used. |
|
|
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | Explicit Gemini TTS selection and Lyria music generation; capture descriptions use `GEMINI_API_KEY`. |
|
|
| `GOOGLE_APPLICATION_CREDENTIALS` / `GCS_CREDS` | Gemini TTS service-account JSON file path / injected JSON. Used when neither API key is set. |
|
|
| `GOOGLE_CLOUD_PROJECT` / `GCLOUD_PROJECT_ID` | Gemini OAuth quota project; first set value wins, then the service account project. |
|
|
| `OPENROUTER_API_KEY` | Capture descriptions; takes priority over Gemini for that step. |
|
|
|
|
## Related topics
|
|
|
|
- [Open the authentication command reference](/packages/cli#hyperframes-auth)
|
|
- [Render with HyperFrames Cloud](/deploy/cloud)
|
|
- [Three ways to start](/quickstart)
|