Concepts
Projects, releases, Beats, the Live Room, viewer sessions, keys and who pays: the words the rest of the docs use.
Projects
A project is one experience, made in the Studio: its scenes, its cast, its story's timeline and its Beats. It belongs to its owner's account, which pays for what the project's own pages use; collaborators edit it, only the owner publishes it.
An embed names a project by its id. A project may also let anyone embed it without a key (the owner then pays), or play only through secure grants (secure-only).
Releases
Publishing makes a release: a numbered, immutable snapshot of the project. One release is live at a time, and a new one goes live atomically once it is built; the owner can make an earlier one live again. A viewer keeps the release they started with until their session ends, even when a newer one goes live.
release: "latest" (the default) plays the live release — or the release a key pins for the project. A release's id plays that release while it exists.
Beats
A Beat is a moment the story waits for the viewer. It has an alias the author gives it (cats_book), which is how your page names it (goToBeat, start: { beat }), and one of three modes:
| Mode | The story goes on when… |
|---|---|
timed | its time runs out, or the viewer continues early where the author allows it. |
gate | the viewer did what it asks — opened the book, answered the quiz. |
open | the viewer continues. Until then they can look around and ask questions. |
Beats are the story's chapters: nextBeat(), prevBeat() and goToBeat() move between them, a gate the viewer has not completed stops a jump past it (gate-locked), and going back past an answered quiz asks the viewer first, because a rewind erases what came after.
The Live Room
The Live Room is the player: the 3D stage, the transport and chapters, captions, the conversation with the characters, quizzes, results and the AI disclosure. The same player runs on the watch page, in the Studio's preview and inside every embed, where it lives in an iframe on embed.jami.live — your page's styles and scripts never reach it, and the jami3d SDK is its remote control.
Viewer sessions
Each viewing is a viewer session, started when the viewer plays. Its token lives 15 minutes and is renewed while the viewer watches; a session ends 8 hours after it began. In an embed, every page load starts a new session.
A session keeps the story's journal: Beats reached, quiz answers and their grades, what the viewer asked. Its result — scores, Beats, completion — is what quizresult, webhooks and the results API report. A rewind starts a new epoch and erases what came after the point it went back to, which is why result.retracted exists.
Keys
| At a glance | Publishable key | Secret key |
|---|---|---|
| Looks like | pk_live_…, pk_test_… | sk_live_…, sk_test_… |
| Lives in | your pages (public by design) | your backend only (shown once) |
| Can | embed the player on the origins it lists: playback, and live AI with text_ai and voice_ai; the conversation's text reaches the page with conversation_events | issue secure-embed grants (sessions), read results (results), usage (usage) and projects (projects) |
A key can be scoped to some of your projects, pinned to a release, and limited (turns and voice seconds per viewer and day, daily and monthly credit caps, concurrent voice). Rotating a key keeps the old one working for a grace you choose; revoking it stops it at once.
Who pays
Live AI — a character's answer, a voice — costs credits; scripted playback, Beats, quizzes and their grading never do, and viewers are never charged. Who pays is decided when the session starts:
| Where it plays | Who pays for its live AI |
|---|---|
| An embed with a publishable key | the key's account — also for another creator's project you embed |
| A secure embed | the account of the secret key that issued the grant |
| A keyless embed, jami.live's own pages | the project's owner |
When the payer's credits or caps run out, live AI pauses and the story goes on: the player says so, and lines the author prepared stand in where there are any. ailevel tells your page what live AI the viewer has (voice, text or off) and why.