[ukimsanov]

What

One paragraph on the Reference video page (/studio-app/reference-video): Reference is part of HyperFrames Pro, and Pro credits pay for the video read when available. A usable saved HeyGen API key pays when the plan can't. A saved key with an empty balance makes the app ask for a key before the read; removing it lets Pro pay. With neither able to pay, the app asks for Pro or a key (Plan & usage when Pro's allowance is used up) and picks the selected video up again once the plan can pay.

Why

The page said Reference always uses your HeyGen API key. Pro users without a key were told to add one they don't need, and the pricing page (Reference Videos under Pro) disagreed with the docs.

Related work

The new "Reverse any video" docs page (local branch docs/reverse-any-video) links here.

How

Docs text only, one paragraph.

Test plan

What I measured (6 Nov 2026):

• The Studio app's source (9 Nov, corrected after review): the plan pays the read when it covers Reference and has credits; a usable saved key pays otherwise. A saved key that can't pay stops the read at the key prompt before any payer is chosen. With neither, the app opens its plan prompt and retries the selected video once the plan pays.
• hyperframes.studio/pricing lists Reference Videos under Pro.
• Documentation updated

What I did NOT exercise: the flow in the app on a Free account and on a Pro account with no key.

How we'll know it worked: no more "Reference asks for an API key but I'm on Pro" questions in the docs assistant logs.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
hyperframes	🟢 Ready	View Preview	Nov 9, 2026, 9:14 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[heygengenesis]

Checked against hyperframes-internal ReferenceAnalysis.tsx readGate and billing/planPays.ts planGate on main. Not approving yet: waiting on Rames.

Correct

• A saved, usable key pays for the read. With no saved key, the gate is planGate(false, "referenceRead") on route /v3/video-analyses, so Pro pays. A missing plan opens openPlan({ feature: "video_analysis" }), and onPlanChanged asks again once the plan pays.
• The pricing page lists Reference Videos under Pro.

Should tighten (not a blocker)

1. A saved key always comes first, even on Pro. If the saved key can't pay (no API balance), readGate returns need: "key", so the app asks for a key and doesn't fall back to Pro. A Pro user with an empty-balance key will hit the key prompt. Suggested addition: "A saved key is always used first. If its balance is empty, the app asks for a key; remove the key in Settings to use Pro instead."
2. "With neither, it opens the plans page" isn't always true. planGate returns need: "key" (the key prompt, not the plans page) when plan payment is off (!pays.on) or plans aren't on sale (hf_plan && !onSale). A Pro account that has used up its allowance gets hf_usage, which opens Plan & usage. That probably matches production today, but "opens the plans page, or Plan & usage if Pro's allowance is used up" would be more accurate.

[jrusso1020]

COMMENT-only review: please correct the billing priority before merging. Reviewed at 6da9308f2b2f924a9671f5437a90ae027640c293.

Important — docs/studio-app/reference-video.mdx:26–28: a saved key does not always pay first. A Pro account with available credits and a valid saved key passes readGate, but the actual read still chooses the plan. readGate is an admission check, not the payer selection. Following that call into Desktop's reference analysis shows planLine() calling payer.choose(); choosePayer() returns the plan for a covered, funded feature even when a key is saved. heygenKeyAccess explicitly preserves this plan-first priority. Source checked at hyperframes-internal d0edcb44e9e7b4843df630f5573cf442e257d363, referenceAnalysis.mjs:153–161,252 and heygenPayerChoice.mjs:39–44.

Please replace “the app uses that key's API balance instead” / “A saved key always comes first” with: “Pro credits pay for the read when available. A usable saved HeyGen API key can pay when the plan cannot.” Keep the distinct UI caveat: a saved empty/rejected key can cause the key prompt before the read starts; removing it lets an eligible Pro plan proceed. This corrects the claim without changing application behavior. It also corrects the payer inference in the earlier review: successful admission with a key is not evidence the key was charged.

Nit: :29–30 still promises the plans page with neither payer. planGate can instead ask for a key when plan payment is unavailable or plans are not on sale. Say “The app asks you to get Pro or add a usable key; when your plan can pay, it retries the selected video.” Used-up Pro usage and resuming only the current selection are source-confirmed.

Source-traced renderer admission → native host → reference read → payer, including funded Pro with/without a key, key without Pro, empty key and missing/exhausted plan cases. Public pricing lists Reference Videos under Pro; all four local links resolve. No live billing/account walkthrough or charges performed.

Need: yes · Size: ok · Reuse: actual read payer rather than admission gate · Simpler: describe plan-first payment and key fallback · Structure: fine (checked shared payer and existing plan gate; no split)
Risk: low — docs only; payment guidance needs the correction above.

Verdict: COMMENT
Reasoning: Please correct the billing priority before merging; the key can admit the read while Pro still pays.

— Rames / hf-review

[heygengenesis]

Re-checked at a7674892 against hyperframes-internal main. The new wording is correct:

• Plan first: choosePayer (heygenPayerChoice.mjs) returns payer: "plan" for a covered, funded feature even with a key saved. /v3/video-analyses isn't marked keyFirst, so Pro pays when it can, and the key pays only for the keyOr(...) cases (not covered, used up, no plan). This corrects my earlier review, which took readGate admission as the payer.
• Empty saved key: readGate still returns need: "key" before the read, so "remove it to let Pro pay" holds.
• Neither: "asks you to get Pro or add a key" covers planGate's need: "key" cases. hf_usage opens Plan & usage, and onPlanChanged retries only the selection on screen.

I'll approve once Rames has reviewed this head and found no blocker.

[jrusso1020]

Reviewed at a76748924dc51ca9888bab67c74f84c0a435b495; delta from 6da9308f2b2f924a9671f5437a90ae027640c293. No remaining blocker.

docs/studio-app/reference-video.mdx:25–31 fixes the previous Important finding: funded Pro credits pay first, and a usable saved key pays when the plan cannot. The empty-balance saved-key prompt is correctly described as occurring before the read. The broader “get Pro or add a key” wording also resolves the earlier prompt caveat; Plan & usage and retrying the selected video agree with the existing plan gate and listener.

Evidence: git diff 6da9308f a7674892 changes only this paragraph; read the full page and rechecked the previously pinned application source at d0edcb44e9e7b4843df630f5573cf442e257d363: actual planLine → choosePayer, renderer admission, plan prompt, and selected-video resume. This is a source review; no live billing/account walkthrough, charges, or application tests performed for this text-only delta.

Need: yes · Size: ok · Reuse: existing payer and plan-gate behavior · Simpler: already minimal · Structure: fine (checked shared payer and existing plan gate; no split)
Risk: low — documentation correction only.

Verdict: COMMENT
Reasoning: The billing priority and prompt caveats now match the implementation; my prior correction request is resolved.

— Rames / hf-review

[heygengenesis]

Approving at a7674892. The wording matches choosePayer: Pro pays first, and a usable saved key pays when the plan cannot. The empty-key prompt and the "get Pro or add a key" ask with Plan & usage also match. Rames found no remaining blocker at this head.