From 0ba8941235f7bb3b40e10bb79bd27130543718c3 Mon Sep 17 00:00:00 2001 From: James Russo Date: Tue, 10 Nov 2026 07:41:52 +0000 Subject: [PATCH] feat(cli): label GPT image prices as estimates and show the charged credits (#7351) * feat(cli): label GPT image prices as estimates and show the charged credits GPT Image generations on a HyperFrames plan are moving to fal's reported vendor cost, so the pre-run figure is an estimate. The --plan basis for gpt-image-2.5, 2.6 and 2.6-flare now reads "about N credits (charged at vendor cost)". Nano Banana is unchanged. When the /v3/images job carries charged.amount, generate reports it as charged_credits and records it in the media ledger's provenance. Without it, nothing new is printed. --max-credits is unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) * feat(cli): keep 10% headroom under --max-credits for vendor-priced images gpt-image-2.5, 2.6 and 2.6-flare are charged at the vendor's cost, so --max-credits now refuses one when its estimate plus 10%, rounded up to a whole credit, is over the limit. A 16:9 gpt-image-2.5 image (about 40 credits) is refused at --max-credits 40 and passes at 44. Other models keep the plain estimate check. The refusal and the --max-credits help say so, and the help notes this is not a hard ceiling. Co-Authored-By: Claude Opus 5.5 (1M context) * fix(cli): count only HyperFrames-credit charges, and keep headroom under the run's limit Review fixes for the vendor-cost image work: - charged_credits is reported only when the job's charged.pool is hyperframes_credits. A charge to api_credits or any other pool is in that pool's own unit, so an API-key caller no longer sees it as HF credits. - runJob logs that charged amount, not the estimate, on a job's completion row in heygen-jobs.jsonl, so later credit-limit checks see the real total. Without a HyperFrames-credit charge the estimate is kept. - The run's credit limit (.hyperframes/credit-limit.json) uses the same 10% headroom rule as --max-credits for gpt-image-2.5, 2.6 and 2.6-flare, through one shared limitCheck helper, with the same refusal wording. Co-Authored-By: Claude Opus 5.5 (1M context) * docs(media-use): say the credit limit is not a hard ceiling for GPT Image A GPT Image call is admitted at its estimate plus 10% but charged the vendor's cost, so it can still go past a run's credit limit. The media-use skill, its HeyGen reference, the --max-credits help and the limit doc strings now say so, and that a finished call's reported charge counts toward the limit afterwards. Other models keep the "refuses what would go past it" wording. No logic change. Co-Authored-By: Claude Opus 5.5 (1M context) * fix(cli): hold a running GPT Image call at its headroom under the project limit A reserved or still-running vendor-priced call was logged at its plain estimate, so two concurrent calls could each pass the 10% headroom check and together go over. Log the headroom amount until HeyGen reports the charge. Co-Authored-By: Claude Opus 5.5 (1M context) --------- Co-authored-by: Claude Opus 5.5 (1M context) --- .../cli/src/commands/media-use/generate.ts | 5 +- packages/cli/src/heygen/generate.test.ts | 131 +++++++++++++++++- packages/cli/src/heygen/generate.ts | 13 ++ packages/cli/src/heygen/pricing.ts | 25 ++-- packages/cli/src/heygen/v3.test.ts | 41 ++++++ packages/cli/src/heygen/v3.ts | 44 +++++- skills-manifest.json | 2 +- skills/media-use/SKILL.md | 2 +- skills/media-use/references/heygen.md | 4 +- 9 files changed, 244 insertions(+), 23 deletions(-) diff --git a/packages/cli/src/commands/media-use/generate.ts b/packages/cli/src/commands/media-use/generate.ts index 02223bc962..7e327b6aa5 100644 --- a/packages/cli/src/commands/media-use/generate.ts +++ b/packages/cli/src/commands/media-use/generate.ts @@ -6,6 +6,7 @@ import { GENERATE_TYPES, checkRequest, generate, + isVendorPriced, parseMask, voiceFor, type GenerateRequest, @@ -141,7 +142,7 @@ export default defineCommand({ "max-credits": { type: "string", description: - "The person's credit limit, less what earlier calls used: make nothing when this call would cost more", + "The person's credit limit, less what earlier calls used: make nothing when this call would cost more. A gpt-image call is charged at the vendor's cost, so it is checked against its estimate plus 10%; that is not a hard ceiling, and an edit with many references can still go over. The project's credit-limit.json follows the same rule", }, plan: { type: "boolean", @@ -195,7 +196,7 @@ export default defineCommand({ next: "run the same command without --plan to make it", }; } - checkLimit(credits, num(args["max-credits"], "--max-credits")); + checkLimit(credits, num(args["max-credits"], "--max-credits"), isVendorPriced(request)); const made = await generate( request, (status) => console.error(`generate: ${status}…`), diff --git a/packages/cli/src/heygen/generate.test.ts b/packages/cli/src/heygen/generate.test.ts index 4ae54677c1..abf1d13f84 100644 --- a/packages/cli/src/heygen/generate.test.ts +++ b/packages/cli/src/heygen/generate.test.ts @@ -1,5 +1,5 @@ import { execFileSync } from "node:child_process"; -import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest"; @@ -45,6 +45,7 @@ const { checkRequest, foldShort, generate, + isVendorPriced, parseMask, pickVoice, ringChange, @@ -143,6 +144,109 @@ describe("generate", () => { expect(ledger).toContain('"references":["ref.png"]'); }); + it("reports and records the credits HeyGen says it charged", async () => { + vi.stubGlobal("fetch", async (url: string) => + url === "https://files.test/charged.png" + ? new Response(new Uint8Array([1])) + : json({ + data: { + id: "img2", + status: "completed", + images: [{ url: "https://files.test/charged.png" }], + charged: { amount: 41, pool: "hyperframes_credits" }, + }, + }), + ); + const r = await generate({ + type: "image", + out: join(project, "assets/charged.png"), + prompt: "a charged picture", + model: "gpt-image-2.5", + }); + expect(r.charged_credits).toBe(41); + expect(readFileSync(join(project, ".media/manifest.jsonl"), "utf8")).toContain( + '"charged_credits":41', + ); + }); + + it("keeps 10% headroom under the run's credit limit for an image charged at the vendor's cost", async () => { + const run = (limit: number) => { + const dir = mkdtempSync(join(tmpdir(), "hf-generate-limit-")); + writeFileSync(join(dir, "index.html"), ""); + mkdirSync(join(dir, ".hyperframes")); + writeFileSync( + join(dir, ".hyperframes/credit-limit.json"), + JSON.stringify({ credits: limit }), + ); + const request = { + type: "image", + out: join(dir, "assets/limited.png"), + prompt: "a limited picture", + model: "gpt-image-2.5", + aspect: "16:9", + } as const; + return generate(request, undefined, creditsOf(priceOf(request)) ?? undefined); + }; + vi.stubGlobal("fetch", async (url: string) => + url === "https://files.test/limited.png" + ? new Response(new Uint8Array([1])) + : json({ + data: { + id: "img4", + status: "completed", + images: [{ url: "https://files.test/limited.png" }], + }, + }), + ); + await expect(run(43)).rejects.toThrow( + "about 40 credits, 44 with 10% headroom because it is charged at the vendor's cost and the run's credit limit of 43 leaves 43", + ); + await expect(run(44)).resolves.toMatchObject({ job: "img4" }); + }); + + it("reports no charge in HyperFrames credits for a charge to another pool", async () => { + vi.stubGlobal("fetch", async (url: string) => + url === "https://files.test/api-charged.png" + ? new Response(new Uint8Array([1])) + : json({ + data: { + id: "img5", + status: "completed", + images: [{ url: "https://files.test/api-charged.png" }], + charged: { amount: 2.46, pool: "api_credits" }, + }, + }), + ); + const r = await generate({ + type: "image", + out: join(project, "assets/api-charged.png"), + prompt: "an api-charged picture", + model: "gpt-image-2.5", + }); + expect(r).not.toHaveProperty("charged_credits"); + }); + + it("reports no charge when HeyGen does not say one", async () => { + vi.stubGlobal("fetch", async (url: string) => + url === "https://files.test/uncharged.png" + ? new Response(new Uint8Array([1])) + : json({ + data: { + id: "img3", + status: "completed", + images: [{ url: "https://files.test/uncharged.png" }], + charged: null, + }, + }), + ); + const r = await generate({ + type: "image", + out: join(project, "assets/uncharged.png"), + prompt: "an uncharged picture", + }); + expect(r).not.toHaveProperty("charged_credits"); + }); + it("sends a picture with no ffmpeg on the machine, shrunk to 2048 px", async () => { const big = join(project, "big.png"); const sharp = await loadSharp("test"); @@ -790,6 +894,15 @@ describe("generate", () => { expect(priceOf({ type: "image", out: "a.png", model: "some-new-model" }).credits).toBeNull(); }); + it("says a GPT Image price is an estimate charged at vendor cost, and a Nano Banana one is not", () => { + expect( + priceOf({ type: "image", out: "a.png", model: "gpt-image-2.5", aspect: "16:9" }).basis, + ).toBe( + "gpt-image-2.5 at 16:9, about 40 credits (charged at vendor cost), with about $0.0125 a reference", + ); + expect(priceOf({ type: "image", out: "a.png" }).basis).toBe("nano-banana-2, $0.067 an image"); + }); + it("prices only a request the real call would accept", () => { // --plan runs the same checks as the real call, so it never prices a request the call would refuse. const [plate, voice] = [join(project, "plate.png"), join(project, "voice.m4a")]; @@ -949,6 +1062,21 @@ describe("generate", () => { expect(() => checkLimit(null, 30)).toThrow("cannot be priced ahead"); expect(() => checkLimit(null, undefined)).not.toThrow(); }); + + it("keeps 10% headroom under the limit for an image charged at the vendor's cost", () => { + const limited = (request: GenerateRequest, limit: number) => () => + checkLimit(creditsOf(priceOf(request)), limit, isVendorPriced(request)); + const gpt = { type: "image", out: "a.png", model: "gpt-image-2.5", aspect: "16:9" } as const; + expect(creditsOf(priceOf(gpt))).toBe(40); + expect(limited(gpt, 40)).toThrow( + "about 40 credits, 44 with 10% headroom because it is charged at the vendor's cost, over --max-credits 40", + ); + expect(limited(gpt, 43)).toThrow("44 with 10% headroom"); + expect(limited(gpt, 44)).not.toThrow(); + const nano = { type: "image", out: "a.png", model: "nano-banana-2" } as const; + expect(isVendorPriced(nano)).toBe(false); + expect(limited(nano, 67)).not.toThrow(); + }); }); describe("each route through the generated client", () => { @@ -1013,6 +1141,7 @@ describe("each route through the generated client", () => { [file, undefined], ]); expect(r).toMatchObject({ route: path, job: polled ? "j/1" : "" }); + expect(r).not.toHaveProperty("charged_credits"); }, ); diff --git a/packages/cli/src/heygen/generate.ts b/packages/cli/src/heygen/generate.ts index 6f908146bb..d658d0a841 100644 --- a/packages/cli/src/heygen/generate.ts +++ b/packages/cli/src/heygen/generate.ts @@ -19,6 +19,7 @@ import { findCuts, signatures } from "../measure/cuts.js"; import { Fix, probeVideo, projectOf, round, runFfmpeg, videoClip } from "../measure/media.js"; import { loadSharp } from "../utils/optionalPackages.js"; import { + chargedCredits, idempotencyKey, keepVoice, keptVoice, @@ -163,6 +164,13 @@ interface Route extends JobRoute { type Media = (path: string, kind: "image" | "audio" | "video") => Record; const DEFAULTS = { image: "nano-banana-2", video: "heygen-video-1", music: "lyria-3-pro" } as const; +export const VENDOR_PRICED_IMAGES = new Set([ + "gpt-image-2.5", + "gpt-image-2.6", + "gpt-image-2.6-flare", +]); +export const isVendorPriced = (r: GenerateRequest): boolean => + r.type === "image" && VENDOR_PRICED_IMAGES.has(r.model ?? ""); const VIDEO_RESOLUTION = "768p"; /** HeyGen follows at most this many seconds of a guide clip; the rest is not sent. */ export const GUIDE_MAX_S = 15; @@ -660,6 +668,7 @@ export interface Generated { cuts_inside?: number[] | null; /** What was changed or looks wrong in the result: a crop to the requested aspect, text that may have come back. */ notes?: string[]; + charged_credits?: number; } // fallow-ignore-next-line complexity @@ -693,6 +702,7 @@ export async function generate( onWait: (j) => onWait?.(j.status), timeoutMs: 30 * 60_000, credits, + vendorPriced: isVendorPriced(r), }); const url = urlOf(job, route.urls); if (!url) @@ -707,6 +717,7 @@ export async function generate( "run the same command again; it re-reads the job", ); writeFileSync(out, Buffer.from(await res.arrayBuffer())); + const charged = chargedCredits(job); // HeyGen sometimes cuts inside a shot on its own; the shot is paid for and kept, the cuts are reported. let cuts: number[] | null | undefined; if (r.type === "video") @@ -761,6 +772,7 @@ export async function generate( : {}), ...(r.voice ? { voice: r.voice } : {}), ...(cuts !== undefined ? { cuts_inside: cuts } : {}), + ...(charged !== undefined ? { charged_credits: charged } : {}), }, }).id; regenerateIndex(project); @@ -773,6 +785,7 @@ export async function generate( ...(ledger ? { ledger } : {}), ...(cuts !== undefined ? { cuts_inside: cuts } : {}), ...(notes.length ? { notes } : {}), + ...(charged !== undefined ? { charged_credits: charged } : {}), }; } finally { rmSync(work, { recursive: true, force: true }); diff --git a/packages/cli/src/heygen/pricing.ts b/packages/cli/src/heygen/pricing.ts index af95ad08aa..cd4b30c3da 100644 --- a/packages/cli/src/heygen/pricing.ts +++ b/packages/cli/src/heygen/pricing.ts @@ -1,7 +1,8 @@ // Prices before a paid call, from the HyperFrames app's creation pricing. HeyGen charges in units of $1/60, rounded // up; the label rounds up to the cent. Routes HeyGen does not price ahead say so instead of guessing. import { Fix, probeSeconds, probeVideo, round } from "../measure/media.js"; -import { GUIDE_MAX_S, type GenerateRequest } from "./generate.js"; +import { GUIDE_MAX_S, VENDOR_PRICED_IMAGES, type GenerateRequest } from "./generate.js"; +import { limitCheck } from "./v3.js"; export interface Price { usd: number | null; @@ -31,7 +32,6 @@ const GPT_IMAGE: Record = { "3:4": 0.03612, }; const GPT_REFERENCE = 0.0125; -const GPT_MODELS = new Set(["gpt-image-2.5", "gpt-image-2.6", "gpt-image-2.6-flare"]); const NANO_IMAGE = 0.067; const NANO_2_1_IMAGE = 0.0336; const NANO_2_1_REFERENCE = 0.00168; @@ -68,12 +68,14 @@ export function priceOf(r: GenerateRequest): Price { NANO_2_1_IMAGE + refs * NANO_2_1_REFERENCE, "nano-banana-2.1, $0.0336 an image and $0.00168 a reference", ); - if (!GPT_MODELS.has(model)) + if (!VENDOR_PRICED_IMAGES.has(model)) return { usd: null, list: null, credits: null, basis: `${model}, not priced ahead` }; const each = GPT_IMAGE[r.aspect ?? "16:9"] ?? GPT_IMAGE["16:9"]!; + const list = each + refs * GPT_REFERENCE; + const about = Math.ceil(list * HF_CREDITS_PER_USD - 1e-9); return at( - each + refs * GPT_REFERENCE, - `${model} at ${r.aspect ?? "16:9"}, about $0.0125 a reference`, + list, + `${model} at ${r.aspect ?? "16:9"}, about ${about} credits (charged at vendor cost), with about $0.0125 a reference`, ); } case "video": { @@ -141,8 +143,12 @@ export function priceOf(r: GenerateRequest): Price { export const creditsOf = (p: Price): number | null => p.credits === null ? null : Math.ceil(p.credits - 1e-9); -/** Refuses, before anything is sent, a call that would not fit what is left of the person's credit limit. */ -export function checkLimit(credits: number | null, limit: number | undefined): void { +/** Refuses, before anything is sent, a call past the limit; a vendor-priced image is checked at its estimate + 10%. */ +export function checkLimit( + credits: number | null, + limit: number | undefined, + vendorPriced = false, +): void { if (limit === undefined) return; const fix = "tell the person what their limit leaves out, then ask whether to raise it or make the video without this piece"; @@ -151,9 +157,10 @@ export function checkLimit(credits: number | null, limit: number | undefined): v `this call cannot be priced ahead, so it cannot be kept under --max-credits ${limit}; nothing was made`, fix, ); - if (credits > limit) + const { checked, about } = limitCheck(credits, vendorPriced); + if (checked > limit) throw new Fix( - `this call is about ${credits} credits, over --max-credits ${limit}; nothing was made or charged`, + `this call is ${about}, over --max-credits ${limit}; nothing was made or charged`, fix, ); } diff --git a/packages/cli/src/heygen/v3.test.ts b/packages/cli/src/heygen/v3.test.ts index cefe6403f2..dd0613a3d7 100644 --- a/packages/cli/src/heygen/v3.test.ts +++ b/packages/cli/src/heygen/v3.test.ts @@ -106,6 +106,47 @@ describe("runJob", () => { expect(calls).toHaveLength(2); }); + it("counts what HeyGen charged in HyperFrames credits, else the estimate", async () => { + const done = (charged: unknown) => + vi.stubGlobal("fetch", async () => + reply(200, { data: { id: "j", status: "completed", charged } }), + ); + const log = project(100); + done({ amount: 41, pool: "hyperframes_credits" }); + await runJob(X, {}, "k1", { log, credits: 60 }); + done(null); + await runJob(X, {}, "k2", { log, credits: 59 }); + await expect(runJob(X, {}, "k3", { log, credits: 1 })).rejects.toThrow(/leaves 0/); + const other = project(100); + done({ amount: 2, pool: "api_credits" }); + await runJob(X, {}, "k1", { log: other, credits: 60 }); + await expect(runJob(X, {}, "k2", { log: other, credits: 59 })).rejects.toThrow(/leaves 40/); + }); + + it("holds a running vendor-priced call at its headroom until HeyGen says what it charged", async () => { + const log = project(87); + vi.stubGlobal("fetch", async () => { + throw new Error("socket hang up"); + }); + await expect(runJob(X, {}, "k1", { log, credits: 40, vendorPriced: true })).rejects.toThrow(); + await expect(runJob(X, {}, "k2", { log, credits: 40, vendorPriced: true })).rejects.toThrow( + /leaves 43/, + ); + const polled = project(87); + const answers = [reply(200, { data: { id: "j", status: "pending" } })]; + vi.stubGlobal("fetch", async () => { + const answer = answers.shift(); + if (!answer) throw new Error("socket hang up"); + return answer; + }); + await expect( + runJob(X, {}, "k1", { log: polled, credits: 40, vendorPriced: true, intervalMs: 1 }), + ).rejects.toThrow(); + await expect( + runJob(X, {}, "k2", { log: polled, credits: 40, vendorPriced: true }), + ).rejects.toThrow(/leaves 43/); + }); + it("refuses a call that cannot be priced ahead", async () => { const calls = sent(); await expect(runJob(X, {}, "k", { log: project(100) })).rejects.toThrow(/cannot be priced/); diff --git a/packages/cli/src/heygen/v3.ts b/packages/cli/src/heygen/v3.ts index 9d583c66e2..ea7b30cb15 100644 --- a/packages/cli/src/heygen/v3.ts +++ b/packages/cli/src/heygen/v3.ts @@ -26,6 +26,24 @@ export interface Job { const RUNNING = new Set(["pending", "processing", "queued", "running", "waiting", "in_progress"]); const isRecord = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); +const VENDOR_HEADROOM = 1.1; + +export const chargedCredits = (job: Job): number | undefined => + isRecord(job.charged) && + job.charged.pool === "hyperframes_credits" && + typeof job.charged.amount === "number" + ? job.charged.amount + : undefined; + +export function limitCheck(credits: number, vendorPriced = false) { + const checked = vendorPriced ? Math.ceil(credits * VENDOR_HEADROOM - 1e-9) : credits; + return { + checked, + about: vendorPriced + ? `about ${credits} credits, ${checked} with 10% headroom because it is charged at the vendor's cost` + : `about ${credits} credits`, + }; +} /** The same request always gets the same key: a re-run is a resume, never a second charge. */ export function idempotencyKey(route: string, parts: readonly (string | Buffer)[]): string { @@ -237,14 +255,17 @@ export interface RunOptions { log?: JobLog; /** What the call is priced at in credits, named in an out-of-credits refusal that does not say. */ credits?: number; + vendorPriced?: boolean; } -/** Refuses, before anything is sent, a new job past the project's credit limit, else reserves its credits. +/** Refuses, before anything is sent, a new job past the project's credit limit, else reserves its credits. A vendor-priced + * image is checked and held at its estimate plus 10%, which its charge can pass, until HeyGen says what it charged. * Every paid call comes through runJob. True when this call reserved. */ function withinLimit( limitLog: JobLog | undefined, sent: string, credits: number | undefined, + vendorPriced?: boolean, ): boolean { if (!limitLog?.projectDir) return false; const limit = creditLimit(limitLog.projectDir); @@ -259,12 +280,13 @@ function withinLimit( `this call cannot be priced ahead, so it cannot be kept under the run's credit limit of ${limit}; nothing was made`, fix, ); - if (credits > left) + const { checked, about } = limitCheck(credits, vendorPriced); + if (checked > left) throw new Fix( - `this call is about ${credits} credits and the run's credit limit of ${limit} leaves ${Math.max(0, left)}; nothing was made or charged`, + `this call is ${about} and the run's credit limit of ${limit} leaves ${Math.max(0, left)}; nothing was made or charged`, fix, ); - log(limitLog, { key: sent, status: "reserved", credits }); + log(limitLog, { key: sent, status: "reserved", credits: checked }); return true; } @@ -280,7 +302,9 @@ export async function runJob( const route = jobRoute.path; const { auth, scope } = await jobSender(); const sent = liveKey(key, scope); - const reserved = withinLimit(opts.log, sent, opts.credits); + const reserved = withinLimit(opts.log, sent, opts.credits, opts.vendorPriced); + const held = + opts.credits === undefined ? undefined : limitCheck(opts.credits, opts.vendorPriced).checked; let job: Job; try { job = await call( @@ -299,7 +323,7 @@ export async function runJob( } const waits = RUNNING.has(job.status.toLowerCase()); if (opts.log && waits) - log(opts.log, { route, id: job.id, key: sent, status: job.status, credits: opts.credits }); + log(opts.log, { route, id: job.id, key: sent, status: job.status, credits: held }); const status = jobRoute.status; while (status && RUNNING.has(job.status.toLowerCase())) { if (Date.now() - started > (opts.timeoutMs ?? 15 * 60_000)) @@ -317,7 +341,13 @@ export async function runJob( ); } if (opts.log) - log(opts.log, { route, id: job.id, key: sent, status: job.status, credits: opts.credits }); + log(opts.log, { + route, + id: job.id, + key: sent, + status: job.status, + credits: chargedCredits(job) ?? opts.credits, + }); if (!/^(completed|succeeded|success|done)$/i.test(job.status)) { markFailed(sent, scope); throw await refusal(422, { diff --git a/skills-manifest.json b/skills-manifest.json index 13afadcf95..5d2e6d901b 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,7 +18,7 @@ "files": 13 }, "media-use": { - "hash": "d28e54e57fce04d9", + "hash": "e00c844c86accb73", "files": 122 }, "remotion-to-hyperframes": { diff --git a/skills/media-use/SKILL.md b/skills/media-use/SKILL.md index a4a2085d98..33cd49a5a3 100644 --- a/skills/media-use/SKILL.md +++ b/skills/media-use/SKILL.md @@ -37,7 +37,7 @@ It prints one line, `resolved → (, )`. List reusab **HeyGen.** `npx hyperframes media-use generate` makes images, shots, talking photos, voices and music on the sign-in alone. Helpers and direct recipes need the [`heygen` CLI](https://developers.heygen.com/cli); if it is missing, give the link and wait until they say it is installed. Direct `heygen` recipes bill that CLI's own login: use them only when that payer is selected. -**Credits.** Plan for the best result: no cheaper or free swaps, no dropped items, unless asked to save cost. Don't volunteer prices, estimates or usage; `--plan` is for you. A credit limit the person sets: write it once to `.hyperframes/credit-limit.json` as `{"credits": N}`; every paid call then refuses what would go past it (`--max-credits` only tightens). A step that won't fit (a `--plan` over what is left, or a refused call): say what doesn't, ask before dropping or shrinking it. A refused call names a `billing` command: say why, ask them to run it, then retry. +**Credits.** Plan for the best result: no cheaper or free swaps, no dropped items, unless asked to save cost. Don't volunteer prices, estimates or usage; `--plan` is for you. A credit limit the person sets: write it once to `.hyperframes/credit-limit.json` as `{"credits": N}`; every paid call then refuses what would go past it, GPT Image only at estimate +10% (`references/heygen.md`) (`--max-credits` only tightens). A step that won't fit (a `--plan` over what is left, or a refused call): say what doesn't, ask before dropping or shrinking it. A refused call names a `billing` command: say why, ask them to run it, then retry. ## Looks on real footage diff --git a/skills/media-use/references/heygen.md b/skills/media-use/references/heygen.md index 53f00e83bb..48544a30e9 100644 --- a/skills/media-use/references/heygen.md +++ b/skills/media-use/references/heygen.md @@ -16,7 +16,7 @@ A refusal names its fix: `api_key_required` needs an API key, `402` or `insuffic ## Making media: `media-use generate` -Make it without quoting a price or asking for a budget; `--plan` only prints what a call would cost (`credits` is an estimate in HyperFrames credits), for your own planning; never pass it on. When the person names a credit limit, record it in the project's credit-limit file (SKILL.md, Credits). Make a piece again only for a fault you can name (a cut inside it, text in it, the wrong framing), once, never to chase a motion or look score; a `content_policy_violation` gets one reworded try. A failed or refused job also gets one more try, test calls included; then stop and ask the person, without saying what was spent or what another try costs. +Make it without quoting a price or asking for a budget; `--plan` only prints what a call would cost (`credits` is an estimate in HyperFrames credits), for your own planning; never pass it on. When the person names a credit limit, record it in the project's credit-limit file (SKILL.md, Credits). A GPT Image call is charged the vendor's cost, so the limit checks it against its estimate plus 10% and is not a hard ceiling for it: a reference-heavy edit can still go past. A finished call's charge, when HeyGen reports it, counts toward the limit afterwards. Make a piece again only for a fault you can name (a cut inside it, text in it, the wrong framing), once, never to chase a motion or look score; a `content_policy_violation` gets one reworded try. A failed or refused job also gets one more try, test calls included; then stop and ask the person, without saying what was spent or what another try costs. ```bash # a still, edited from a reference picture: a clean plate with the words removed @@ -48,7 +48,7 @@ The file lands at `--out` and the media ledger records it as generated, with the | Type | Model | Price | | ------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| image | nano-banana-2 (default), or nano-banana-2.1, gpt-image-2.5, gpt-image-2.6 or gpt-image-2.6-flare with `--model` | $0.067 an image; nano-banana-2.1 $0.034 plus $0.0017 a reference; gpt-image $0.036–0.053 by aspect, plus about $0.0125 for every reference | +| image | nano-banana-2 (default), or nano-banana-2.1, gpt-image-2.5, gpt-image-2.6 or gpt-image-2.6-flare with `--model` | $0.067 an image; nano-banana-2.1 $0.034 plus $0.0017 a reference; gpt-image about $0.036–0.053 by aspect plus $0.0125 a reference, a plan charges vendor cost | | video | heygen-video-1, 768p | $0.02 a second from a prompt or first frame; $0.05 a second with a reference picture, voice or guide clip, and the guide's seconds count too (1080p costs about twice) | | lipsync | HeyGen lipsync, speed | 7 credits a second of the video on a plan | | avatar | talking photo | $4.83 a minute of speech |