mirror of
https://github.com/hanzoai/frames.git
synced 2026-09-24 00:08:03 +00:00
zooqueen
75094e0d60
@hanzo/frame is taken by the hero video primitive — one full-bleed video element — which has held that name on npm since it shipped. This repo is the video toolchain: a CLI, a renderer, a studio, a player. Plural is what it is, so the CLI publishes as @hanzo/frames and the workspace packages follow it (@hanzo/frames-core, @hanzo/frames-engine, and the rest). The binary stays `frames`, and now actually ships. The manifest mapped it to bin/frames.mjs while the file on disk was bin/hyperframes.mjs, so a global install produced no working command. The paths that name a package to fetch were pointing elsewhere. The update check read registry.npmjs.org/frames, a different author's package, and the npm, bun and pnpm installers would have pulled it over the CLI; the render image installed the upstream hyperframes; scaffolded projects and the docs pinned the unscoped name. All of them now name @hanzo/frames.
84 lines
4.0 KiB
Plaintext
84 lines
4.0 KiB
Plaintext
---
|
|
title: Authentication
|
|
description: "One credential for voice, music, sound effects, images, video, the shared media catalog, and cloud rendering — a Hanzo IAM token, read from Hanzo KMS."
|
|
---
|
|
|
|
Frames talks to one host, `api.hanzo.ai`, with one credential: a Hanzo IAM
|
|
token in `HANZO_API_KEY`. The same token covers voiceover, word timings, music,
|
|
sound effects, images, video, the shared media catalog, and cloud rendering.
|
|
There is no per-capability key and no second account.
|
|
|
|
## Set the credential
|
|
|
|
<Steps>
|
|
<Step title="Read the token from Hanzo KMS">
|
|
Secrets live in [Hanzo KMS](https://kms.hanzo.ai) — never in a file beside
|
|
the project, never in a per-repo `.env`, never in the repo.
|
|
|
|
```bash
|
|
export HANZO_API_KEY=... # a Hanzo IAM token, or an sk- cloud key
|
|
export HANZO_ORG=... # the tenant that owns the shared media bucket
|
|
```
|
|
|
|
In CI the pipeline injects both; nothing is written to disk.
|
|
</Step>
|
|
<Step title="Confirm what's configured">
|
|
```bash
|
|
npx @hanzo/frames auth status
|
|
```
|
|
|
|
Shows which credential is in use and the identity behind it. Exit 0 means
|
|
usable; exit 1 means absent or rejected — a normal state in scripts
|
|
(`auth status || echo offline`), not a command failure.
|
|
|
|
For the media skills specifically:
|
|
|
|
```bash
|
|
node <MEDIA_DIR>/scripts/resolve.mjs --doctor
|
|
```
|
|
</Step>
|
|
</Steps>
|
|
|
|
A publishable `pk-` key is read-only and the media routes refuse it; use an IAM
|
|
token or an `sk-` key. Point at a different deployment — a Hanzo Engine on your
|
|
own machine, for instance — with `HANZO_BASE_URL`.
|
|
|
|
## What the credential unlocks
|
|
|
|
| Capability | Route | Without a credential |
|
|
|---------------------|----------------------------------|---------------------------------------------|
|
|
| **Voice** | `POST /v1/audio/speech` | unavailable |
|
|
| **Word timings** | `POST /v1/audio/transcriptions` | unavailable; captions fall back to line timing |
|
|
| **Music** | `POST /v1/audio/music` | unavailable |
|
|
| **Sound effects** | `POST /v1/audio/foley` | the 21 bundled effects still resolve |
|
|
| **Images** | `POST /v1/images/generations` | unavailable |
|
|
| **Video** | `POST /v1/videos/generations` | unavailable |
|
|
| **Shared catalog** | `GET /v1/s3/buckets/media/…` | unavailable (also needs `HANZO_ORG`) |
|
|
| **Color grades / LUTs** | built locally from `params` | unaffected — deterministic and offline |
|
|
| **Cloud rendering** | see [Cloud rendering](/deploy/cloud) | render locally instead |
|
|
|
|
The shared catalog is a listing of files under `media/<type>/` in our own object
|
|
store. It is empty until it is stocked, and an empty prefix is reported as
|
|
empty rather than read as a bad query — music and images then generate instead.
|
|
|
|
## Working without a credential
|
|
|
|
No credential is a normal state, not an error, but it is a smaller one than it
|
|
used to be: the bundled sound effects and the local color-grade and LUT builders
|
|
work offline; everything else is a network call. `--local-only` makes that
|
|
explicit — it skips every network provider and leaves the project and global
|
|
caches.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Used for |
|
|
|----------|----------|
|
|
| `HANZO_API_KEY` | The Hanzo IAM token. Read it from Hanzo KMS. |
|
|
| `HANZO_ORG` | The tenant that owns the shared media bucket. Needed for catalog reads. |
|
|
| `HANZO_BASE_URL` | API base URL (default `https://api.hanzo.ai`). Point it at a local Hanzo Engine to run the same code offline. |
|
|
| `OPENROUTER_API_KEY` | Capture descriptions during [website capture](/guides/website-to-video). |
|
|
|
|
See the [`frames auth`](/packages/cli#frames-auth) command reference for
|
|
subcommand details, and [Cloud rendering](/deploy/cloud) for using the same
|
|
token to render in the cloud.
|