Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Price fal clips by what fal bills, and keep dear models to end-frame shots

Claude277c849d76cb
diff --git a/client/src/components/musicVideo/ProjectOptionsPanel.jsx b/client/src/components/musicVideo/ProjectOptionsPanel.jsx
index 21ea449764..e2c8dcf947 100644
--- a/client/src/components/musicVideo/ProjectOptionsPanel.jsx
+++ b/client/src/components/musicVideo/ProjectOptionsPanel.jsx
@@ -133,7 +133,7 @@ export default function ProjectOptionsPanel({
<div className={rowCls}>
<span className={headCls}>Video service</span>
<div className="flex min-w-0 flex-wrap items-center gap-2">
- <VideoRenderSettings videoSettings={videoSettings} generating={generatingVideos} />
+ <VideoRenderSettings videoSettings={videoSettings} generating={generatingVideos} project={project} />
</div>
</div>
<div className={rowCls}>
diff --git a/client/src/components/musicVideo/VideoRenderSettings.jsx b/client/src/components/musicVideo/VideoRenderSettings.jsx
index b99c4e1cc7..fa8f0224e8 100644
--- a/client/src/components/musicVideo/VideoRenderSettings.jsx
+++ b/client/src/components/musicVideo/VideoRenderSettings.jsx
@@ -1,8 +1,10 @@
import RenderPoolPicker from './RenderPoolPicker.jsx';
import { GROK_VIDEO_DURATIONS } from '../../lib/grokVideoClip.js';
import {
- FAL_AUDIO_VIDEO_MODEL, FAL_DEFAULT_IMAGE_VIDEO_MODEL, FAL_IMAGE_VIDEO_MODELS, describeFalVideoRate, falVideoResolutions, getFalVideoModel,
+ FAL_AUDIO_VIDEO_MODEL, FAL_DEFAULT_IMAGE_VIDEO_MODEL, FAL_IMAGE_VIDEO_MODELS, describeFalVideoRate, falImageVideoQuotes, falVideoResolutions, getFalVideoModel,
} from '../../lib/falVideoModels.js';
+import { projectFalSpend } from '../../lib/musicVideoStages.js';
+import { formatUsd } from '../../utils/formatters.js';
import { SOURCE_AUDIO_LIPSYNC, SOURCE_AUDIO_MUSIC, performanceCapability } from '../../lib/musicVideoShotTiming.js';
const falSelectCls = 'w-full max-w-full bg-port-bg border border-port-border rounded px-1.5 py-1.5 text-sm disabled:opacity-50 sm:w-auto min-h-[44px] sm:min-h-0';
@@ -16,7 +18,7 @@ const falOptionLabel = (model) => {
// persists through useMusicVideoModelSettings' `change`, and locks while a save
// is in flight or any scene clip is generating, so the job payload and the
// board's displayed setting cannot disagree.
-export default function VideoRenderSettings({ videoSettings, generating }) {
+export default function VideoRenderSettings({ videoSettings, generating, project = null }) {
const {
settings, saving, models, modelsLoading, defaultModel, effectiveModelId,
audioReactiveModels, audioReactiveLoras, detectedAudioReactiveLora,
@@ -39,6 +41,10 @@ export default function VideoRenderSettings({ videoSettings, generating }) {
// an audio-to-video model where the song slice drives the whole frame.
const music = performanceCapability('fal', { scene: { performanceStyle: 'music' }, videoSettings: settings });
const musicModels = Object.values(SOURCE_AUDIO_MUSIC.fal);
+ // A dearer start+end-frame model is an explicit upgrade for end-frame shots
+ // only; each option shows what a typical short (2 s) shot bills.
+ const endFrameQuotes = falImageVideoQuotes({ seconds: 2, endFrame: true });
+ const falSpend = project ? projectFalSpend(project) : null;
return (
<>
<RenderPoolPicker settings={settings} change={change} disabled={locked} />
@@ -207,6 +213,20 @@ export default function VideoRenderSettings({ videoSettings, generating }) {
</select>
</>
)}
+ <label htmlFor="mv-fal-end-frame-model" className="sr-only">fal.ai model for end-frame shots</label>
+ <select
+ id="mv-fal-end-frame-model"
+ value={settings.falEndFrameModelId || ''}
+ onChange={(e) => change({ falEndFrameModelId: e.target.value || null })}
+ disabled={locked}
+ title="Model for shots with a style-break end frame only. Every other shot keeps the cutaway model above."
+ className={`${falSelectCls} sm:max-w-[280px]`}
+ >
+ <option value="">End-frame shots: same model</option>
+ {endFrameQuotes.map((quote) => (
+ <option key={quote.modelId} value={quote.modelId}>{`End-frame shots: ${quote.label} · ${formatUsd(quote.costUsd)} per short shot`}</option>
+ ))}
+ </select>
<label htmlFor="mv-fal-duration" className="sr-only">fal.ai scene clip duration</label>
<input
id="mv-fal-duration"
@@ -280,6 +300,12 @@ export default function VideoRenderSettings({ videoSettings, generating }) {
</select>
</>
)}
+ {falSpend?.totalUsd > 0 && (
+ <p className="w-full min-w-0 break-words text-xs text-port-text-muted" title="Estimated from the price each fal render was quoted at; fal's own invoice is the final word">
+ {`fal spend (est.) ${formatUsd(falSpend.totalUsd)}: `}
+ {falSpend.models.map((row) => `${row.label} ${formatUsd(row.usd)} (${row.count})`).join(' · ')}
+ </p>
+ )}
</>
);
}
diff --git a/client/src/hooks/useMusicVideoModelSettings.js b/client/src/hooks/useMusicVideoModelSettings.js
index f56de184fb..d579e30842 100644
--- a/client/src/hooks/useMusicVideoModelSettings.js
+++ b/client/src/hooks/useMusicVideoModelSettings.js
@@ -73,6 +73,8 @@ export default function useMusicVideoModelSettings({ project, onProjectPatch } =
// MUSIC_VIDEO_LIPSYNC_DEFAULT_RESOLUTION), resolved by falSceneTake.
falModelId: project?.videoSettings?.falModelId ?? null,
falResolution: project?.videoSettings?.falResolution ?? null,
+ // Upgrade model for end-frame shots only; null = they use falModelId.
+ falEndFrameModelId: project?.videoSettings?.falEndFrameModelId ?? null,
falLipSyncResolution: project?.videoSettings?.falLipSyncResolution ?? null,
// false = lip-sync without transcript guidance (null/absent = on).
falLipSyncTranscription: project?.videoSettings?.falLipSyncTranscription ?? null,
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index 6325ac35ff..c744791a0d 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -68,7 +68,7 @@ grep -i "what you want to do" client/src/lib/README.md
| `musicVideoCoverOverlay.js` | Cover-art lettering preview (#10345): re-export of `server/lib/musicVideoCoverOverlay.js` (the design vocabulary, `normalizeCoverDesign`, `coverOverlaySvg`) plus `canvasCoverWidths(design, texts, fonts)`, which measures text with a canvas so the live preview wraps and sizes the title the way the server's measured render does. |
| `musicVideoSceneTiming.js` | `buildSceneTimingPresentation`: pure provider timing, cost, coverage and split/merge projection for the Music Video scene card, reusing canonical shot-timing policy. |
| `musicVideoShotTiming.js` | Re-export of `server/lib/musicVideoShotTiming.js` (#8977) — shot modes and performance styles, the verified source-audio lip-sync and music-driven capability tables, `performanceBlockedReason`, `planPerformanceRepair` (measured accepted-prefix boundary, suffix interval and next spend), `planPerformanceWindow`, `grokCoverage`, `approximateMotionCues`, `shotSplitLimit` (when a scene offers a lyric-boundary split), `falSceneTake` (a fal take's model, length, resolution and estimated cost). `clipAudioOffsetSec` (how far into an aligned take's clip its audio window starts, #11210). Used by `hooks/useMusicVideoSceneMedia.js` and `components/musicVideo/SceneCard.jsx`. |
-| `musicVideoStages.js` | Music Video page stage model: `MUSIC_VIDEO_STAGES` (six steps: Song `setup` → Look `cast-sets` → Storyboard `board` → Make `produce` → Final render `review` → Publish; a retired `compose` link resolves to Make), `resolveStageParam(value)` for the `:stage` route param, `deriveStages(project)` (per-stage `done`/`active`/`blocked`/`todo` + `current`, the first incomplete step; a live production run pins Make), `deriveNextAction(project, ctx)` (the one primary action the sticky header offers — approve Cast & Sets, verify lyric timing, stop/resume production, render final, …), `describeProjectStatus` (the header line and the step that needs the director), `autopilotStatus` (the header Autopilot button), `projectSpend(project)` (paid generation used vs. cap), `projectShotSummary(project)` (document shots or scene counts), `stageChecklist(stageId, project, readiness)` (what one step still needs, with the open approval's reason and a scroll anchor; an `optional` item, such as Make's animated proof, is listed but not counted), `summarizeStoryboardProblems(problems)` (folds the server's one-sentence-per-shot storyboard problems into one count line per kind), `stepNotes(project, readiness, publish)` (one fact per step for the step list), `listPreviewSources` (final, live composition, drafts, then the storyboard animatic), `projectServicesSummary(project)` (the saved image/video render services), `compareMusicVideoProjectsNewestFirst(a, b)` (sort projects newest created / updated first for project cards and pickers), and `currentProductionRun`; `productionReviewStopGuidance` separates current approval blockers from historical run stops. Used by `components/musicVideo/MusicVideoLayout.jsx` and `pages/MusicVideo.jsx`. |
+| `musicVideoStages.js` | Music Video page stage model: `MUSIC_VIDEO_STAGES` (six steps: Song `setup` → Look `cast-sets` → Storyboard `board` → Make `produce` → Final render `review` → Publish; a retired `compose` link resolves to Make), `resolveStageParam(value)` for the `:stage` route param, `deriveStages(project)` (per-stage `done`/`active`/`blocked`/`todo` + `current`, the first incomplete step; a live production run pins Make), `deriveNextAction(project, ctx)` (the one primary action the sticky header offers — approve Cast & Sets, verify lyric timing, stop/resume production, render final, …), `describeProjectStatus` (the header line and the step that needs the director), `autopilotStatus` (the header Autopilot button), `projectSpend(project)` (paid generation used vs. cap), `projectShotSummary(project)` (document shots or scene counts), `stageChecklist(stageId, project, readiness)` (what one step still needs, with the open approval's reason and a scroll anchor; an `optional` item, such as Make's animated proof, is listed but not counted), `summarizeStoryboardProblems(problems)` (folds the server's one-sentence-per-shot storyboard problems into one count line per kind), `stepNotes(project, readiness, publish)` (one fact per step for the step list), `listPreviewSources` (final, live composition, drafts, then the storyboard animatic), `projectServicesSummary(project)` (the saved image/video render services), `compareMusicVideoProjectsNewestFirst(a, b)` (sort projects newest created / updated first for project cards and pickers), and `currentProductionRun`; `productionReviewStopGuidance` separates current approval blockers from historical run stops. Used by `components/musicVideo/MusicVideoLayout.jsx` and `pages/MusicVideo.jsx`. `projectFalSpend(project)` (estimated fal.ai spend by model across paid takes and production steps). |
| `musicVideoAttention.js` | Music Video "Needs attention" model (#9940): `deriveAttentionItems(project, live)` returns the banner rows for server-held states a client-orchestrated workflow can strand — an open/rendering revision, an interrupted Cast & Sets stage, a running auto-review waiting on its revised sections, a final render nobody is watching — derived from the persisted record so they survive a reload (healthy work this tab can see progressing is not flagged); `openRevisionOf(project)`; `ATTENTION_ANCHOR_ID` + `revealAttention()` scroll a refusal toast to the banner. Used by `components/musicVideo/NeedsAttentionBanner.jsx` and `pages/MusicVideo.jsx`. |
| `musicVideoProjectList.js` | Music Video project index model (#10167): `projectRunPill(project)` (Running / Needs you / Interrupted / Done, from the same next-action and attention logic as the header), `groupMusicVideoProjects(projects, query)` (collapse forks under their root, newest version first, name filter, groups ordered by last touch), and `compareMusicVideoProjectsRecentlyTouched`. Used by `pages/MusicVideo.jsx` and `components/musicVideo/MusicVideoProjectCard.jsx`. |
| `musicVideoPreview.js` | Pick the representative produced asset for a Music Video project card (`selectMusicVideoPreview`: final video → latest excerpt → latest rendered scene clip → latest scene reference frame → visual spec reference) for the main project grid. Pure, computed off the project record, with image path and fallback helpers (`musicVideoImageSrc`, `musicVideoImageFallback`, `scenePosterSrc`: a scene's frame or its clip's poster). |
diff --git a/client/src/lib/falVideoModels.js b/client/src/lib/falVideoModels.js
index 7bc03d3137..ed8abb70b8 100644
--- a/client/src/lib/falVideoModels.js
+++ b/client/src/lib/falVideoModels.js
@@ -14,6 +14,8 @@ export {
FAL_VIDEO_MODELS,
describeFalVideoRate,
estimateFalVideoCostUsd,
+ falImageVideoQuotes,
+ falVideoClipQuote,
falVideoResolutions,
getFalVideoModel,
} from '../../../server/lib/falVideoModels.js';
diff --git a/client/src/lib/musicVideoStages.js b/client/src/lib/musicVideoStages.js
index 33ebb69422..af3d7c98b2 100644
--- a/client/src/lib/musicVideoStages.js
+++ b/client/src/lib/musicVideoStages.js
@@ -12,6 +12,7 @@ import { formatCount, formatDurationSec, formatTimecode } from '../utils/formatt
import { isNonBlankStr } from './textUtils';
import { modeLabel } from './imageGenModes.js';
import { falSceneTake } from './musicVideoShotTiming.js';
+import { getFalVideoModel } from './falVideoModels.js';
import { latestMusicVideoReviewDraft } from '../../../server/lib/musicVideoReviewDraft.js';
import { FINISHED_OUTSIDE_RERENDER_NOTE, finishedOutside, finishedOutsideCovers } from '../../../server/lib/musicVideoFinishedOutside.js';
@@ -109,6 +110,37 @@ export function projectSpend(project) {
return { spentUsd, capUsd, autopilot, manual, autoReview, total: spentUsd };
}
+/**
+ * What the project has spent on fal.ai, by model, from the estimates its paid
+ * takes and production-run steps recorded: `{ totalUsd, models: [{ modelId,
+ * label, usd, count }] }`, dearest first. `modelId` is null for spend recorded
+ * before takes named their model. Estimates, not fal's invoice; a take pruned
+ * from a full scene no longer counts.
+ */
+export function projectFalSpend(project) {
+ const byModel = new Map();
+ const add = (modelId, usd) => {
+ if (!(Number.isFinite(usd) && usd > 0)) return;
+ const key = modelId || null;
+ const row = byModel.get(key) || { modelId: key, label: key ? getFalVideoModel(key)?.label || key : 'Model not recorded', usd: 0, count: 0 };
+ row.usd += usd;
+ row.count += 1;
+ byModel.set(key, row);
+ };
+ for (const scene of Array.isArray(project?.scenes) ? project.scenes : []) {
+ for (const take of Array.isArray(scene?.takes) ? scene.takes : []) {
+ if (take?.spendKind) add(take.costModelId, Number(take.costUsd));
+ }
+ }
+ for (const run of Array.isArray(project?.productionRuns) ? project.productionRuns : []) {
+ for (const step of Array.isArray(run?.steps) ? run.steps : []) {
+ if (step?.route?.mode === 'fal' && step.status !== 'refused') add(step.costModelId || step.route.model, Number(step.costUsd));
+ }
+ }
+ const models = [...byModel.values()].map((row) => ({ ...row, usd: Math.round(row.usd * 1e4) / 1e4 })).sort((a, b) => b.usd - a.usd);
+ return { totalUsd: Math.round(models.reduce((sum, row) => sum + row.usd, 0) * 1e4) / 1e4, models };
+}
+
/**
* What generating the rest of the board takes (#10157): scenes still missing a
* frame or a clip, the generation limit that covers them plus a 25% review
diff --git a/client/src/lib/musicVideoStages.test.js b/client/src/lib/musicVideoStages.test.js
index a22e016614..19a72be3b6 100644
--- a/client/src/lib/musicVideoStages.test.js
+++ b/client/src/lib/musicVideoStages.test.js
@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest';
import { summarizeMusicVideoProject } from '../../../server/lib/musicVideoSummary.js';
import {
changedFieldsText,
- MUSIC_VIDEO_STAGES, currentProductionRun, deriveNextAction, deriveStages, projectSpend, boardJobEstimate, listPreviewSources, describeProjectStatus, resolveStageParam, stageChecklist, stepNotes, autopilotStatus, compareMusicVideoProjectsNewestFirst,
+ MUSIC_VIDEO_STAGES, currentProductionRun, deriveNextAction, deriveStages, projectSpend, projectFalSpend, boardJobEstimate, listPreviewSources, describeProjectStatus, resolveStageParam, stageChecklist, stepNotes, autopilotStatus, compareMusicVideoProjectsNewestFirst,
} from './musicVideoStages.js';
const APPROVED = { art: { approved: true }, storyboard: { approved: true }, proof: { approved: true }, readyForProduction: true };
@@ -726,3 +726,29 @@ describe('server project summary', () => {
expect(stages.map(([summary]) => summary)).toEqual(['setup', 'cast-sets', 'produce', 'produce', 'review', 'publish']);
});
});
+
+describe('projectFalSpend', () => {
+ it('breaks paid takes and fal production steps down by model, dearest first', () => {
+ const KLING = 'fal-ai/kling-video/v3/pro/image-to-video';
+ const HAILUO = 'fal-ai/minimax/hailuo-02/standard/image-to-video';
+ const project = {
+ scenes: [scene({ takes: [
+ { takeId: 'a', spendKind: 'manual', costUsd: 0.7, costModelId: KLING },
+ { takeId: 'b', spendKind: 'autoReview', costUsd: 0.7, costModelId: KLING },
+ { takeId: 'c', spendKind: 'manual', costUsd: 0.1 },
+ { takeId: 'd' },
+ ] })],
+ productionRuns: [run({ steps: [
+ { route: { kind: 'video', mode: 'fal', model: null }, costModelId: HAILUO, costUsd: 0.27, status: 'completed' },
+ { route: { kind: 'video', mode: 'fal', model: null }, costModelId: HAILUO, costUsd: 0.27, status: 'refused' },
+ { route: { kind: 'video', mode: 'local', model: null }, costUsd: 0, status: 'completed' },
+ ] })],
+ };
+ expect(projectFalSpend(project)).toEqual({ totalUsd: 1.77, models: [
+ { modelId: KLING, label: 'Kling v3 Pro (image)', usd: 1.4, count: 2 },
+ { modelId: HAILUO, label: 'MiniMax Hailuo-02 Standard (image)', usd: 0.27, count: 1 },
+ { modelId: null, label: 'Model not recorded', usd: 0.1, count: 1 },
+ ] });
+ expect(projectFalSpend({})).toEqual({ totalUsd: 0, models: [] });
+ });
+});
diff --git a/server/lib/falVideoModels.js b/server/lib/falVideoModels.js
index b938784200..1cc91dad34 100644
--- a/server/lib/falVideoModels.js
+++ b/server/lib/falVideoModels.js
@@ -183,7 +183,9 @@ export const FAL_VIDEO_MODELS = Object.freeze([
aspectRatio: null,
negativePrompt: 'native',
audio: { param: 'generate_audio', providerDefault: true },
- pricing: { perSecond: 0.112, perSecondWithAudio: 0.168 },
+ // What fal actually bills (an invoice, 2026-10-11: $0.14/s with audio off),
+ // not the model page's $0.112; the audio-on rate is scaled by the same 1.25.
+ pricing: { perSecond: 0.14, perSecondWithAudio: 0.21 },
},
{
id: 'fal-ai/veo3.1/fast/image-to-video', kind: 'i2v', label: 'Veo 3.1 Fast (image)', family: 'veo-3.1',
@@ -196,8 +198,10 @@ export const FAL_VIDEO_MODELS = Object.freeze([
negativePrompt: 'native',
audio: { param: 'generate_audio', providerDefault: true },
seed: 'seed',
+ // The same invoice billed a silent (generate_audio: false) 4 s clip at the
+ // audio-on $0.15/s, so silence saves nothing here: priced at what is billed.
pricing: {
- perSecond: { '720p': 0.1, '1080p': 0.1, '4k': 0.3 },
+ perSecond: { '720p': 0.15, '1080p': 0.15, '4k': 0.35 },
perSecondWithAudio: { '720p': 0.15, '1080p': 0.15, '4k': 0.35 },
},
},
@@ -281,16 +285,27 @@ function perSecondRate(model, resolution, withAudio) {
const round4 = (n) => Math.round(n * 1e4) / 1e4;
+/** The shortest clip fal bills `model` for (seconds): its shortest delivered length, or its audio minimum. */
+function falVideoMinBilledSec(model) {
+ const rule = model?.duration;
+ if (!rule) return null;
+ if (rule.kind === 'audio') return model.audioInput?.minSec ?? null;
+ return rule.kind === 'enum' ? rule.values[0] : rule.min;
+}
+
/**
- * Estimated USD for one fal render, or null when the model is not curated or
- * the inputs cannot be priced. `seconds` is what the caller asks for; it is
- * coerced exactly as the request body will be (a lip-sync take is billed on
- * its audio length). `width`/`height` only matter for token-priced models
- * (Seedance), where a canvas wider than 16:9 costs proportionally more; a
- * narrower one is still priced at the 16:9 figure so the estimate never
- * undershoots. `generateAudio` selects the audio-on rate where one exists.
+ * What one fal render costs and why, or null when the model is not curated or
+ * the inputs cannot be priced: `{ modelId, label, requestedSec, billedSec,
+ * minBilledSec, resolution, perSec, costUsd }`. `seconds` is what the caller
+ * asks for; `billedSec` is the length fal renders and bills — coerced exactly
+ * as the request body will be, so a 2 s shot on a model whose shortest clip is
+ * 6 s bills 6 s (a lip-sync take is billed on its audio length). `width`/
+ * `height` only matter for token-priced models (Seedance), where a canvas wider
+ * than 16:9 costs proportionally more; a narrower one is still priced at the
+ * 16:9 figure so the estimate never undershoots. `generateAudio` selects the
+ * audio-on rate where one exists.
*/
-export function estimateFalVideoCostUsd({ modelId, seconds, resolution, width, height, generateAudio = false } = {}) {
+export function falVideoClipQuote({ modelId, seconds, resolution, width, height, generateAudio = false } = {}) {
const model = getFalVideoModel(modelId);
if (!model) return null;
let billedSec;
@@ -314,22 +329,56 @@ export function estimateFalVideoCostUsd({ modelId, seconds, resolution, width, h
if (perSec == null) return null;
const long = model.pricing.longTake;
const factor = long && billedSec > long.overSec ? long.factor : 1;
- return round4(perSec * billedSec * factor);
+ const requested = Number(seconds);
+ return {
+ modelId: model.id,
+ label: model.label,
+ requestedSec: Number.isFinite(requested) && requested > 0 ? requested : null,
+ billedSec,
+ minBilledSec: falVideoMinBilledSec(model),
+ resolution: res,
+ perSec: round4(perSec),
+ costUsd: round4(perSec * billedSec * factor),
+ };
}
-/** A one-line human rate for `model` at `resolution`, e.g. "$0.16/s at 1080P (×1.2 over 15s)". */
+/** Estimated USD for one fal render (`falVideoClipQuote`'s `costUsd`), or null when it cannot be priced. */
+export const estimateFalVideoCostUsd = (options = {}) => falVideoClipQuote(options)?.costUsd ?? null;
+
+/**
+ * Every curated start-frame model priced for one shot of `seconds`, cheapest
+ * first — what a per-shot model picker lists. `endFrame: true` keeps only the
+ * models that take an end frame. Each entry is a `falVideoClipQuote` plus
+ * `endFrame` (whether the model takes one); a model with no price is left out.
+ */
+export function falImageVideoQuotes({ seconds, resolution = null, endFrame = false } = {}) {
+ return FAL_IMAGE_VIDEO_MODELS
+ .filter((model) => !endFrame || model.endImage)
+ .map((model) => {
+ const quote = falVideoClipQuote({ modelId: model.id, seconds, resolution });
+ return quote ? { ...quote, endFrame: Boolean(model.endImage) } : null;
+ })
+ .filter(Boolean)
+ .sort((a, b) => a.costUsd - b.costUsd || a.perSec - b.perSec);
+}
+
+/**
+ * A one-line human rate for `model` at `resolution`, with the shortest clip fal
+ * bills, e.g. "$0.045/s at 768P · bills 6s min" or "$0.16/s at 1080P (×1.2 over 15s)".
+ */
export function describeFalVideoRate(modelId, resolution) {
const model = getFalVideoModel(modelId);
if (!model) return null;
const res = resolveFalVideoResolution(model, resolution);
+ const min = model.duration.kind === 'audio' ? '' : ` · bills ${falVideoMinBilledSec(model)}s min`;
if (model.pricing.videoTokensPerSec16x9) {
const perSec = model.pricing.videoTokensPerSec16x9[res];
- return perSec == null ? null : `≈$${perSec.toFixed(4)}/s at ${res} (16:9)`;
+ return perSec == null ? null : `≈$${perSec.toFixed(4)}/s at ${res} (16:9)${min}`;
}
const perSec = perSecondRate(model, res, false);
if (perSec == null) return null;
const long = model.pricing.longTake;
- return `$${perSec}/s${res ? ` at ${res}` : ''}${long ? ` (×${long.factor} over ${long.overSec}s)` : ''}`;
+ return `$${perSec}/s${res ? ` at ${res}` : ''}${long ? ` (×${long.factor} over ${long.overSec}s)` : ''}${min}`;
}
/**
diff --git a/server/lib/falVideoModels.test.js b/server/lib/falVideoModels.test.js
index 83960d72b0..76caa829e1 100644
--- a/server/lib/falVideoModels.test.js
+++ b/server/lib/falVideoModels.test.js
@@ -6,6 +6,8 @@ import {
buildFalVideoRequest,
coerceFalVideoSeconds,
estimateFalVideoCostUsd,
+ falImageVideoQuotes,
+ falVideoClipQuote,
getFalVideoModel,
} from './falVideoModels.js';
@@ -105,9 +107,10 @@ describe('estimateFalVideoCostUsd — list prices per family', () => {
// H3 Max at list price (not the launch promo), H3 Turbo half that.
expect(estimateFalVideoCostUsd({ modelId: 'minimax/h3-max/image-to-video', seconds: 6, resolution: '1080P' })).toBe(0.96);
expect(estimateFalVideoCostUsd({ modelId: 'minimax/h3-max-turbo/image-to-video', seconds: 5, resolution: '480P' })).toBe(0.125);
- // Kling / Veo: audio-off vs audio-on rates.
- expect(estimateFalVideoCostUsd({ modelId: 'fal-ai/kling-video/v3/pro/image-to-video', seconds: 5 })).toBe(0.56);
- expect(estimateFalVideoCostUsd({ modelId: 'fal-ai/kling-video/v3/pro/image-to-video', seconds: 5, generateAudio: true })).toBe(0.84);
+ // Kling / Veo: the billed audio-off vs audio-on rates (Veo bills silence at the audio rate).
+ expect(estimateFalVideoCostUsd({ modelId: 'fal-ai/kling-video/v3/pro/image-to-video', seconds: 5 })).toBe(0.7);
+ expect(estimateFalVideoCostUsd({ modelId: 'fal-ai/kling-video/v3/pro/image-to-video', seconds: 5, generateAudio: true })).toBe(1.05);
+ expect(estimateFalVideoCostUsd({ modelId: 'fal-ai/veo3.1/fast/image-to-video', seconds: 4 })).toBe(0.6);
expect(estimateFalVideoCostUsd({ modelId: 'fal-ai/veo3.1/fast/image-to-video', seconds: 8, resolution: '4k', generateAudio: true })).toBe(2.8);
});
@@ -136,3 +139,25 @@ describe('estimateFalVideoCostUsd — list prices per family', () => {
}
});
});
+
+describe('per-clip quotes — what a shot actually bills', () => {
+ const HAILUO = 'fal-ai/minimax/hailuo-02/standard/image-to-video';
+ const KLING = 'fal-ai/kling-video/v3/pro/image-to-video';
+
+ it('bills a short shot at the model\'s shortest clip, not the shot length', () => {
+ expect(falVideoClipQuote({ modelId: HAILUO, seconds: 2 })).toMatchObject({ requestedSec: 2, billedSec: 6, minBilledSec: 6, perSec: 0.045, costUsd: 0.27 });
+ expect(falVideoClipQuote({ modelId: KLING, seconds: 2 })).toMatchObject({ billedSec: 3, minBilledSec: 3, perSec: 0.14, costUsd: 0.42 });
+ expect(falVideoClipQuote({ modelId: 'example/uncurated-model', seconds: 2 })).toBeNull();
+ });
+
+ it('lists start-frame models cheapest first, only end-frame capable ones when asked', () => {
+ const all = falImageVideoQuotes({ seconds: 2 });
+ const rank = (id) => all.findIndex((q) => q.modelId === id);
+ expect(rank(HAILUO)).toBeLessThan(rank(KLING));
+ expect(all.map((q) => q.costUsd)).toEqual([...all.map((q) => q.costUsd)].sort((a, b) => a - b));
+ const endFrame = falImageVideoQuotes({ seconds: 2, endFrame: true });
+ expect(endFrame.every((q) => q.endFrame && getFalVideoModel(q.modelId).endImage)).toBe(true);
+ expect(endFrame.map((q) => q.modelId)).toContain(KLING);
+ expect(endFrame.map((q) => q.modelId)).not.toContain('fal-ai/veo3.1/fast/image-to-video');
+ });
+});
diff --git a/server/lib/musicVideoShotTiming.js b/server/lib/musicVideoShotTiming.js
index 4442bfd7ae..be670e235b 100644
--- a/server/lib/musicVideoShotTiming.js
+++ b/server/lib/musicVideoShotTiming.js
@@ -454,7 +454,10 @@ export function planShotSplit({ startSec, endSec, maxSec, lyricCues, phrases, be
* renders on `videoSettings.falModelId` (default Hailuo-02 image-to-video) at
* `falResolution` (default: the model's), for the pinned `falDuration` or else
* the shot's span — rounded UP to a length the model delivers, so the clip
- * covers the shot. An uncurated model keeps the legacy contract (only an
+ * covers the shot. A shot with a style-break end frame renders on
+ * `videoSettings.falEndFrameModelId` when the project picked one that takes an
+ * end frame — a dearer model is an explicit upgrade for those shots only, never
+ * the footage default. An uncurated model keeps the legacy contract (only an
* explicit pin is sent) and reports cost unknown.
*
* Returns `{ performance, modelId, seconds, resolution, costUsd }`; `seconds`
@@ -480,7 +483,9 @@ export function falSceneTake({ scene, videoSettings = {}, songDurationSec = null
costUsd: seconds == null ? null : estimateFalVideoCostUsd({ modelId: capability.modelId, seconds, resolution }),
};
}
- const modelId = settings.falModelId || FAL_DEFAULT_IMAGE_VIDEO_MODEL;
+ const endFrameModel = typeof scene?.endImageId === 'string' && scene.endImageId.trim()
+ ? getFalVideoModel(settings.falEndFrameModelId) : null;
+ const modelId = endFrameModel?.endImage ? endFrameModel.id : settings.falModelId || FAL_DEFAULT_IMAGE_VIDEO_MODEL;
const model = getFalVideoModel(modelId);
if (!model) {
return { performance: false, modelId, seconds: settings.falDuration || null, resolution: settings.falResolution || null, costUsd: null };
diff --git a/server/lib/musicVideoShotTiming.test.js b/server/lib/musicVideoShotTiming.test.js
index b67a4382f0..d18df1343d 100644
--- a/server/lib/musicVideoShotTiming.test.js
+++ b/server/lib/musicVideoShotTiming.test.js
@@ -111,6 +111,18 @@ describe('music-driven performance takes', () => {
});
});
+describe('fal model per shot', () => {
+ it('uses the end-frame upgrade only on shots with an end frame, and only a model that takes one', () => {
+ const KLING = 'fal-ai/kling-video/v3/pro/image-to-video';
+ const shot = { sceneId: 's', startSec: 0, endSec: 2 };
+ const videoSettings = { falEndFrameModelId: KLING };
+ expect(falSceneTake({ scene: shot, videoSettings })).toMatchObject({ modelId: 'fal-ai/minimax/hailuo-02/standard/image-to-video', seconds: 6, costUsd: 0.27 });
+ expect(falSceneTake({ scene: { ...shot, endImageId: 'sketch.png' }, videoSettings })).toMatchObject({ modelId: KLING, seconds: 3, costUsd: 0.42 });
+ expect(falSceneTake({ scene: { ...shot, endImageId: 'sketch.png' }, videoSettings: { falEndFrameModelId: 'fal-ai/veo3.1/fast/image-to-video' } }).modelId)
+ .toBe('fal-ai/minimax/hailuo-02/standard/image-to-video');
+ });
+});
+
describe('accepted-prefix repair planning', () => {
const scene = { shotMode: 'performance', sceneId: 'example', videoHistoryId: 'clip', startSec: 10, endSec: 24,
takes: [{ kind: 'video', assetId: 'clip', shotInstruction: { shotMode: 'performance',
diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.js
index 5577db4ac4..0308875d4a 100644
--- a/server/lib/musicVideoValidation.js
+++ b/server/lib/musicVideoValidation.js
@@ -147,6 +147,9 @@ export const musicVideoVideoSettingsSchema = z.object({
// null/omitted = the default model (Hailuo-02 image-to-video) / its default.
falModelId: z.string().min(1).max(200).nullable().optional(),
falResolution: z.string().min(1).max(16).nullable().optional(),
+ // Upgrade model for shots with a style-break end frame (one that takes an
+ // end frame, e.g. Kling v3 Pro); null/omitted = those shots use falModelId.
+ falEndFrameModelId: z.string().min(1).max(200).nullable().optional(),
// Output resolution of a performance (lip-sync) take — fal's own alphabet
// for the lip-sync route. null/omitted = MUSIC_VIDEO_LIPSYNC_DEFAULT_RESOLUTION.
falLipSyncResolution: z.enum(SOURCE_AUDIO_LIPSYNC.fal.resolutions).nullable().optional(),
diff --git a/server/services/musicVideo/production.js b/server/services/musicVideo/production.js
index fa46b8591b..5812d4ac84 100644
--- a/server/services/musicVideo/production.js
+++ b/server/services/musicVideo/production.js
@@ -597,7 +597,7 @@ function castAndSetsGate(project, run) {
* Returns `{ project, run, step }`.
*/
export function reserveProductionStep(project, runId, {
- kind, sceneId, revisionId = null, route, rationale = '', processId, costUsd: stepCostUsd = undefined, plateRepairBasis = null,
+ kind, sceneId, revisionId = null, route, rationale = '', processId, costUsd: stepCostUsd = undefined, costModelId = null, plateRepairBasis = null,
}, now = new Date().toISOString()) {
let step = null;
const out = mutateRun(project, runId, (run) => {
@@ -647,6 +647,7 @@ export function reserveProductionStep(project, runId, {
route: { kind: route.kind, mode: route.mode, model: route.model || null },
rationale: trimTo(rationale, MAX_ERROR_LEN) || '',
costUsd,
+ ...(costUsd !== null && isNonBlankStr(costModelId) ? { costModelId: trimTo(costModelId, 200) } : {}),
...(['frame', 'clip'].includes(kind) ? { retryBasis: productionRetryBasis(project, sceneId, kind) } : {}),
...(['frame', 'clip'].includes(kind) ? { providerBasis: productionProviderBasis(project, kind) } : {}),
...(kind === 'clip' && scene?.direction?.actionContract ? { plateAdmission: { assetId: scene.referenceImageId, basis: plateRequirementBasis(scene) } } : {}),
diff --git a/server/services/musicVideo/productionPool.js b/server/services/musicVideo/productionPool.js
index e8ed23b5ab..ef50cf60e4 100644
--- a/server/services/musicVideo/productionPool.js
+++ b/server/services/musicVideo/productionPool.js
@@ -95,6 +95,19 @@ export function stepPriceUsd({ route, project, scene, stepKind }) {
return routePriceUsd(route, project);
}
+/**
+ * The paid model a step's price is for, recorded on the step so project spend
+ * can be broken down by model: the fal clip model `stepPriceUsd` priced (an
+ * end-frame upgrade included), a fal image route's own model, else null.
+ */
+export function stepCostModelId({ route, project, scene, stepKind }) {
+ if (route?.mode !== 'fal') return null;
+ if (stepKind !== 'frame' && route.kind === 'video' && scene) {
+ return falSceneTake({ scene, videoSettings: falRouteVideoSettings(project, route) }).modelId;
+ }
+ return route.model || null;
+}
+
/** routeKey → price map for a pool (fal routes priced for `project`). */
export const poolPricing = (pool, project = null) => Object.fromEntries(pool.map((r) => [routeKey(r), routePriceUsd(r, project)]));
diff --git a/server/services/musicVideo/productionService.js b/server/services/musicVideo/productionService.js
index a84151a426..81fdd09073 100644
--- a/server/services/musicVideo/productionService.js
+++ b/server/services/musicVideo/productionService.js
@@ -74,6 +74,7 @@ import {
chooseProductionRoute,
loadPoolEnv,
poolPricing,
+ stepCostModelId,
stepPriceUsd,
sceneRequirement,
} from './productionPool.js';
@@ -312,6 +313,7 @@ async function dispatchSlot(projectId, runId, { stepKind, sceneId, revisionId =
const reserved = await mutateProjectRecord(projectId, (current) => reserveProductionStep(current, runId, {
kind: stepKind, sceneId, revisionId, plateRepairBasis, route: choice.route, rationale: choice.rationale, processId: PROCESS_ID,
costUsd: stepPriceUsd({ route: choice.route, project: current, scene: (current.scenes || []).find((s) => s.sceneId === sceneId), stepKind }),
+ costModelId: stepCostModelId({ route: choice.route, project: current, scene: (current.scenes || []).find((s) => s.sceneId === sceneId), stepKind }),
})).catch((err) => ({ error: err }));
if (reserved.error) {
const code = reserved.error.code;
diff --git a/server/services/musicVideo/projectsLogic.js b/server/services/musicVideo/projectsLogic.js
index f98d40a932..bfe461c11e 100644
--- a/server/services/musicVideo/projectsLogic.js
+++ b/server/services/musicVideo/projectsLogic.js
@@ -133,6 +133,7 @@ export function buildProjectRecord(input, { id, now }) {
falDuration: videoSettings.falDuration ?? null,
falModelId: videoSettings.falModelId ?? null,
falResolution: videoSettings.falResolution ?? null,
+ falEndFrameModelId: videoSettings.falEndFrameModelId ?? null,
falLipSyncResolution: videoSettings.falLipSyncResolution ?? null,
falMusicModelId: videoSettings.falMusicModelId ?? null,
falMusicResolution: videoSettings.falMusicResolution ?? null,
@@ -399,6 +400,7 @@ export function applyProjectPatch(project, patch) {
falDuration: null,
falModelId: null,
falResolution: null,
+ falEndFrameModelId: null,
falLipSyncResolution: null,
falMusicModelId: null,
falMusicResolution: null,
diff --git a/server/services/musicVideo/takes.js b/server/services/musicVideo/takes.js
index 1fa301cdef..d6202fef17 100644
--- a/server/services/musicVideo/takes.js
+++ b/server/services/musicVideo/takes.js
@@ -52,7 +52,7 @@ const clip = (v, max) => (isNonBlankStr(v) ? trimTo(v, max) : null);
// A basename only — an imported file's name is provenance, never a path.
const takeOriginalName = (name) => (isNonBlankStr(name) ? clip(name.split(/[\\/]/).pop(), 200) : null);
-function buildTake({ kind, assetId, source, provider = null, jobId = null, prompt = null, sourceImageId = null, originalName = null, shotInstruction = null, use = 'final', dependencies = null, inputAssets = null, costUsd = null, spendKind = null, now }) {
+function buildTake({ kind, assetId, source, provider = null, jobId = null, prompt = null, sourceImageId = null, originalName = null, shotInstruction = null, use = 'final', dependencies = null, inputAssets = null, costUsd = null, spendKind = null, costModelId = null, now }) {
return {
takeId: `mvt-${randomUUID()}`,
kind,
@@ -71,7 +71,11 @@ function buildTake({ kind, assetId, source, provider = null, jobId = null, promp
note: null,
createdAt: now,
// #10157: the quoted generation cost, present only on a priced paid take.
- ...(Number.isFinite(costUsd) && costUsd >= 0 ? { costUsd, spendKind: spendKind === 'autoReview' ? 'autoReview' : 'manual' } : {}),
+ ...(Number.isFinite(costUsd) && costUsd >= 0 ? {
+ costUsd, spendKind: spendKind === 'autoReview' ? 'autoReview' : 'manual',
+ // The paid model the quote priced, so project spend can say where it went.
+ ...(isNonBlankStr(costModelId) ? { costModelId: clip(costModelId, 200) } : {}),
+ } : {}),
// #8977: the immutable record of what a performance take was generated
// against (audio revision, song interval, edit in/out, cues, capability).
// Present only on takes that carry one, so other takes keep their shape.
diff --git a/server/services/musicVideoSceneVideoHook.js b/server/services/musicVideoSceneVideoHook.js
index d67a89f624..f4b4301650 100644
--- a/server/services/musicVideoSceneVideoHook.js
+++ b/server/services/musicVideoSceneVideoHook.js
@@ -98,6 +98,7 @@ const hook = createMediaJobImageHook({
// #10157: the estimate this clip was priced at; a revision-tagged job is
// an auto-review generation, the rest are manual takes.
costUsd: job.params?.musicVideoCostUsd ?? null,
+ costModelId: job.params?.musicVideoCostModelId ?? null,
spendKind: job.params?.musicVideo?.revisionId ? 'autoReview' : 'manual',
}]),
onAttached: ({ projectId, sceneId, videoHistoryId }, { scene, appended }) => {
diff --git a/server/services/videoGen/fal.test.js b/server/services/videoGen/fal.test.js
index 02d76484da..ee10581fe5 100644
--- a/server/services/videoGen/fal.test.js
+++ b/server/services/videoGen/fal.test.js
@@ -168,8 +168,8 @@ describe('videoGen/fal — generateVideo', () => {
duration: '8', generate_audio: false,
});
const [entry] = await loadHistory();
- // 8s (the covering length) × $0.112/s audio off.
- expect(entry).toMatchObject({ modelId: 'fal:fal-ai/kling-video/v3/pro/image-to-video', duration: 8, generateAudio: false, estimatedCostUsd: 0.896 });
+ // 8s (the covering length) × $0.14/s audio off.
+ expect(entry).toMatchObject({ modelId: 'fal:fal-ai/kling-video/v3/pro/image-to-video', duration: 8, generateAudio: false, estimatedCostUsd: 1.12 });
if (input === 'upload') {
await vi.waitFor(async () => {
await expect(readFile(framePath)).rejects.toMatchObject({ code: 'ENOENT' });
diff --git a/server/services/videoGen/submitJob.js b/server/services/videoGen/submitJob.js
index 96294fe1d0..25ab287d94 100644
--- a/server/services/videoGen/submitJob.js
+++ b/server/services/videoGen/submitJob.js
@@ -307,7 +307,7 @@ const submitValidatedVideoGenJob = async (body, uploads) => {
// step is already charged to the run's own usage, so it is skipped.
if (scene && backend === VIDEO_GEN_MODE.FAL && !body.musicVideo.productionRunId) {
const { falSceneTake } = await import('../../lib/musicVideoShotTiming.js');
- const { costUsd } = falSceneTake({
+ const { costUsd, modelId: costModelId } = falSceneTake({
scene,
videoSettings: {
falMusicModelId: project.videoSettings?.falMusicModelId ?? null,
@@ -316,7 +316,7 @@ const submitValidatedVideoGenJob = async (body, uploads) => {
},
songDurationSec: project.audioAnalysis?.durationSec ?? null,
});
- if (Number.isFinite(costUsd)) params.musicVideoCostUsd = costUsd;
+ if (Number.isFinite(costUsd)) Object.assign(params, { musicVideoCostUsd: costUsd, musicVideoCostModelId: costModelId });
}
}
// Selective section revision (#9011): checked as the LAST step before the