wikis / Imagination Studio / wiki / concepts / models-and-weights.md view as markdown report a mistake
Models and Weights
Definition
Imagination Studio does not ship model weights; setup downloads them from their owners. Three things describe what a machine has and can run:
- The model catalog,
app/model_catalog.json: model descriptors, download manifests, published byte sizes, checksum pins and declared admission policies. - Shared measurements,
app/model_measurements.json: portable observations from actual recipe checks on named hardware. - Local qualification receipts: per-machine evidence kept outside Git, produced by Machine โ Feature checks.
Settings โ Models & weights (the README's and the Windows guide's name; the installation guide calls the Mac and Linux page Machine โ Models & weights) is the page that shows them together. Facts are from main as fetched 2026-11-19 (VERSION 4.5.0). The runtime policies, measurements and qualification described here chiefly concern native Windows: the catalog's notes speak of Windows recipe envelopes, and the measurements guide says no Mac or Spark measurements are checked in. Mac and Linux model choices by install flag are on install mac and install dgx spark.
How It Works
The model catalog
The catalog (schema 1) groups its entries as below. The size column is the sum of the published byte sizes the catalog lists for that part's files, converted to decimal GB by this wiki; the catalog itself stores bytes per file, checked at 2026-11-05T20:48:07.750663+00:00. Sizes are model payload, not RAM requirements or a total disk estimate.
| Group | Catalog id | Label | Download part and source repository | Listed payload |
|---|---|---|---|---|
| Picture models | qwen |
Qwen-Image 2.1 Turbo | image: Comfy-Org/Qwen-Image-2.1 (Turbo transformer, text encoder, VAE) |
24.26 GB |
| Picture models | qwen-full |
Qwen-Image 2.1 Full | image plus image-edit (qwen_image_2.1_bf16.safetensors) |
14.23 GB more |
| Picture models | flux3k-fast, flux3k-full |
FLUX3-K Fast, FLUX3-K Full | flux3: black-forest-labs/flux-3-image-klein-comfy and flux-3-image-klein-pup; one download holds both transformers |
41.13 GB |
| Picture models | moss-image |
MOSS-Image | moss: Comfy-Org/MOSS-Image |
29.72 GB |
| Video | video |
FastH3 | video: FastVideo/FastVideo-FastH3-Comfy (transformer, text encoder, video and audio VAE) |
74.64 GB |
| Video | ref2va |
MiniMax H3 references | ref2va: Comfy-Org/MiniMax-H3 (bf16 Ref2VA transformer and a Turbo LoRA) |
42.18 GB |
| Voice | voice |
Fish Audio Drama 3 | checkpoint fishaudio/drama-3 |
41.50 GB (whole snapshot) |
| Music | music |
MiniMax-Music3 | music: Comfy-Org/MiniMax-Music-3 |
21.84 GB |
| Brain | bolt |
NVIDIA Nemotron 3.5 Bolt | nvidia/NVIDIA-Nemotron-3.5-Bolt-74B-A9B-24GB and its -LiLiCorr companion |
24.12 GB and 0.96 GB |
| Sound | sound |
Stable Audio Open | sound: stabilityai/stable-audio-open-1.0 |
5.29 GB |
| Sound | stable-audio-3-small-sfx |
Stable Audio 3 Small SFX | stabilityai/stable-audio-3-small-sfx (a separate Comfy-Org/stable-audio-3 snapshot is listed for a Spark) |
3.49 GB |
| Sound | foley |
MMAudio Foley | Kijai/MMAudio_safetensors and nvidia/bigvgan_v2_44khz_128band_512x |
5.12 GB and 0.49 GB |
| Library workflows | h3-shared |
H3 shared text encoder and decoders | h3-shared: three files of the FastH3 repository |
30.56 GB |
| Library workflows | library-h3 |
Library H3 bf16 transformer | library-h3: minimax_h3_ref2va_pruned_bf16.safetensors |
40.23 GB |
| Library workflows | workflows |
Library workflows | SAM 3.1 (Comfy-Org/sam3.1) and the H3 latent upscaler (LBH-123-AI/Minimax_h3_latent_Upscaler) |
1.75 GB and 0.69 GB |
| Character Swap | swap |
Character Swap | int8 Ref2VA transformer, Character Swap LoRA v1.5, LightX2V 8-step Turbo LoRA, SAM 3.1 | 20.97, 0.16, 1.96 and 1.75 GB |
| Training | train |
H3 training | H3 video VAE fp16, a training adapter, minimax_h3_fl2va_pruned_bf16.safetensors |
5.21, 0.31 and 40.23 GB |
Parts overlap: video and h3-shared list the same text encoder and decoders, and ref2va and library-h3 the same bf16 transformer, so the figures must not be added into a total.
What each model does is on picture generation, video generation, voice and dialogue, music and sound and local brains.
Declared admission policies in the catalog
Each entry has a runtime block. Most say "required_free_gib": null with basis unknown ("No general Windows recipe envelope established; use local per-recipe qualification."). Four values are declared, all with basis policy:
| Model | Route | required_free_gib |
Catalog note |
|---|---|---|---|
| Fish Audio Drama 3 | cuda |
50.0 | Measured Spark peak about 41.6 GiB plus engine reserve; not a Windows minimum-RAM measurement |
| MiniMax-Music3 | int8 |
30.0 | Based on Spark observations plus reserve; not a Windows minimum-RAM measurement |
| MiniMax-Music3 | bf16 |
38.0 | Same |
| NVIDIA Nemotron 3.5 Bolt | cuda |
43.0 | Includes runtime state and reserve; not a Windows minimum-RAM measurement |
The Windows guide gives the consequence for voice: a 64 GB N1X may expose about 30.5 GiB to its GPU, which cannot meet Voice's current 50 GiB free-pool admission policy.
Licences, as the catalog and README give them
The catalog carries no licence field; it lists licence files inside some downloads (LICENSE.md for Stable Audio Open, LICENSE.md and LICENSE_GEMMA.md for Stable Audio 3 Small SFX, LICENSE for Drama 3). The README states:
- Studio code is Apache-2.0. Models and bundled tools retain their own licences.
- "Qwen-Image-2.1 and MMAudio weights are non-commercial; MiniMax H3 has territory limits; Fish Audio hosted services need separate licensing."
- Check each model's terms before commercial use. Weights are not redistributed by the repository.
FLUX3-K and Stable Audio Open require Hugging Face access approval: accept the repository's terms with the same account used by the local Hugging Face login or token. HF_TOKEN, if set, takes precedence over the saved login. The full treatment is on licensing and attribution.
Settings โ Models & weights
On Windows each row shows installed components at the configured Windows path, download size, runtime-fit information and a native PowerShell setup command. In place means files are installed, not that every recipe has passed a render check. Sections can be collapsed; headings summarize installed, missing, found and conversion states.
How a missing model is treated:
| State | Meaning |
|---|---|
| Known insufficient capacity | Automatic selection skips the model and its engine build; an explicit install stops before tooling/downloads unless the mismatch is acknowledged |
| Temporary contention | Current free memory is lower than required, but the pool could meet the policy; not a permanent unsupported-machine result |
| Unknown fit | No declared envelope for that route; not labelled a success or a capacity failure |
| Below 128 GiB RAM, matching shared failures with no passes | Missing-model downloads are blocked before setup; automatic setup skips the component. At 128 GiB or more, shared failures warn only |
| Mixed shared results | Download allowed, with a warning that other presets failed |
| No matching shared metadata | Setup logs a warning and continues; missing evidence alone never blocks |
The UI withholds an incompatible missing model's setup command until download anyway is acknowledged; the copied command then includes -AllowInsufficientModel. For the image-only installer, -AllowUnverifiedImageModel accepts matching failed image recipes. Neither flag changes runtime guards. -NoDownload and complete cached weights stay reusable; -PlanOnly performs no probes or installation.
Where local recipe evidence exists, a model's row summarizes passed/total and failed recipes, and shows observed peak ranges separately for adapter-wide GPU usage and owned job commitment. The GPU figure includes other applications, neither range is a minimum requirement, and the two overlap, so do not add them. A + marks a range that includes a memory-limited run stopped before completion.
On a Mac and a DGX Spark the installation guide describes Machine โ Models & weights as the list of weights the Studio found elsewhere on the machine, linked, or still needing a download or a conversion, with Use it and Unlink. python3 app/discover.py --scan shows the same table; nothing is moved or copied.
How measurements work and where they are stored
app/model_measurements.jsonis a schema-1 document withgenerated_at, apurposeline ("Shared observations, not local passes, minimum RAM requirements or guaranteed fit.") and aprofileslist. As fetched it holds 20 profiles.- Each profile has
model,feature,scope,outcome,checked_at,identity(recipe, contracts, weight hashes and byte sizes),hardwarepools,runtime_versions,observations,interrupted,provenance_complete,executionandprovenance. - An observation records
elapsed_s,peak_job_commit_mb,rendered,samples,minimum_free_mb(host_available_mb,host_commit_headroom_mb,dedicated_gpu_free_mb),gpu_pool_mbandcommit_limit_mb. All quantities ending in_mbare MiB. - Every profile in the file records
physical_total_mb65536 andgpu_dedicated_total_mb31232 on platformwindows; the measurements guide says the observations come from a Windows ARM64 RTX Spark (N1X) with one unified-memory device. There are currently no checked-in Mac or Spark measurements. - Outcomes in the file: 12
passed, 7commit_reserve(interrupted) and 1memory_refusal(thevoiceprofile).
Representative entries, all from that one configuration (physical_total_mb 65536):
| Model, scope | Recipe | Outcome | elapsed_s |
peak_job_commit_mb |
|---|---|---|---|---|
qwen, basic |
512ร512, count 1 | passed |
56.176 | 28471.90625 |
qwen, studio |
1024ร576, count 1 | passed |
63.836 | 29027.1796875 |
qwen, basic (another attempt) |
not recorded | commit_reserve, interrupted |
37.223 | 28208.8515625 |
Rules the measurements guide sets for reading them:
- Shared results never create local passes; a successful reference is not local qualification.
- Do not replace an admission requirement with an observed peak, or treat a failed run as a measured minimum. Interrupted samples are incomplete lower bounds.
- Pools are never added. Adapter-wide GPU usage includes other processes.
- A 128 GiB machine's success does not prove a smaller machine can run that recipe. Failure evidence applies to equal or lower capacities on the same route; successful evidence is not extrapolated down.
Feature checks and qualification (Windows)
Open Machine โ Feature checks to run a check. Checks are opt-in renders on the machine through the normal one-at-a-time queue; opening the page, starting the Studio or downloading a model never runs inference automatically.
| Installed physical RAM | Qualification gating and badges |
|---|---|
| Below 128 GiB, or capacity unknown | Required; unverified recipes stay gated |
| 128 GiB or more | Off by default and optional |
- Each passed recipe enables its tested settings. Groups run recipes sequentially and keep individual passes; a failed larger check does not remove smaller passes.
- Each model/backend has independent results: Turbo's pass does not qualify Qwen Full or FLUX3-K. Image recipes check exact canvases and sequential counts.
- Buttons: Check this feature, Check selected recipes, Rerun check, Cancel check; Refresh status and Download saved report only read diagnostics.
- Green checkmarks mean complete, yellow progress partial, a red cross an unchecked recipe that failed.
- Video has several checks: Small 5 s, Small 15 s, Full size 5, 10 and 15 s, and Long videos and a starting picture.
- The Library actions Turnaround, Upscale, Find a person, Remove a person and Character Swap have independent cards.
- All machines keep installation prerequisites, backend-specific policies, supported recipe bounds and live memory admission/kill guards. The 128 GiB threshold is a verification-policy default, not a guarantee that every model fits.
STUDIO_QUALIFICATION_STRICT=1opts into exact provenance matching; the default balanced matching keeps dated evidence across compatible source/tool updates.
Platform detail is on install windows rtx spark.
History of the panel. The 4.4.1 release note says the screens went back to 4.3.1's. Issue #233 (closed as completed on 2026-11-15) reported that this rollback had also removed the Feature checks UI and its badges while the qualification backend remained. The 4.5.0 release note lists: "Feature checks (ivberg's #247): the checks, qualification guidance and model diagnostics are back."
Running and updating measurement sweeps (Windows)
Use the real running native Studio on 127.0.0.1:7870 with the intended models installed. Never start a hidden second app, lower guards, change GPU carve-outs or automatically install models for a sweep.
$Python = "$env:LOCALAPPDATA\ImaginationStudio\ui-venv\Scripts\python.exe"
# Export only existing actual receipts: no GPU/hardware probes or inference.
& $Python -X utf8 scripts\measure-windows-models.py --export-only --output measurements.json
# Default: plan recipes without a complete compatible shared pass. Does not render.
& $Python -X utf8 scripts\measure-windows-models.py --output measurements.json
# Run only the three updated models, using their registered scopes.
& $Python -X utf8 scripts\measure-windows-models.py --models qwen,qwen-full,flux3k-full --run --output measurements.json
# Limit an image campaign to a particular recipe.
& $Python -X utf8 scripts\measure-windows-models.py --models qwen --scopes studio --run --output measurements.json
# Force all installed registered native model recipes, even with matching shared evidence.
& $Python -X utf8 scripts\measure-windows-models.py --force-all --run --output measurements.json
- Scope: Qwen Turbo/Full, FLUX3-K Fast/Full, MOSS-Image, native Voice/Music and the five native Library actions.
- A sibling
.resume.jsontracks the submitted job; keep it to resume, and use a new output filename for a fresh forced campaign. Ctrl+C cancels the submitted job and exports available receipts. - The runner stops on any failed or cancelled recipe. The invocation has a 24-hour deadline;
--timeout-hoursoverrides it.--reference other-measurements.jsoncompares against another campaign. - To check results in: review the JSON, merge reviewed schema-1
profilesintoapp/model_measurements.jsondeduplicating by profileid, run the tests, then stage and commit yourself. The tool never stages, commits or pushes, and nothing is uploaded automatically. - Refresh published file sizes without downloading weights:
py -3.13 -X utf8 scripts\refresh-model-sizes.py. - Tests:
py -3.13 -X utf8 -m pytest -q tests\test_shared_measurements.py tests\test_model_catalog.py tests\test_windows_setup_fit.py.
Uninstalling a model (Windows)
- In Models & weights, on an installed catalog model choose Remove model weights โ Copy uninstall command. This only copies a command; nothing is deleted through the browser.
- Stop the Studio and its engines.
- Run the command in PowerShell. It previews the exclusive weight files and asks to confirm by typing the model id.
-PlanOnlypreviews without prompting or deleting.
Shared files are preserved. Engines, environments, configuration, projects, media, cached downloads and qualification receipts stay intact. Linked, junction or hard-linked weights and external model overrides are refused by the helper and need manual review. Engine-only rows and SD-Turbo do not offer this action.
Key Parameters
| Name | Meaning |
|---|---|
app/model_catalog.json |
Descriptors, manifests, byte sizes, checksum pins, admission policies |
app/model_measurements.json |
Shared schema-1 observations |
-AllowInsufficientModel |
setup-windows-cuda.ps1: overrides the shared-failure gate and the declared-capacity gate |
-AllowUnverifiedImageModel |
setup-windows-images.ps1: overrides shared image failures only |
-NoDownload, -PlanOnly |
Skip the model-download stage; plan with no probes or installation |
-Parts |
setup-windows-cuda.ps1 component selection, e.g. image, voice, music, workflows, h3-shared, library-h3 |
STUDIO_QUALIFICATION_STRICT=1 |
Exact provenance matching for qualification |
STUDIO_WINDOWS_FEATURE_DIR |
Overrides where qualification receipts are kept (default: the runtime root's qualification directory) |
| 128 GiB | Installed-RAM threshold below which gating is required and shared failures block downloads |
When To Use
- Before downloading a large model on a Windows machine under 128 GiB: read its row in Models & weights for observed memory and the download recommendation.
- After installing a model on such a machine: run its recipes in Machine โ Feature checks, smallest first.
- After moving an install: qualification receipts are not carried over; run the checks again on the destination (see launching updating and access).
- When contributing measurements: run a changed-only sweep and merge reviewed profiles.
Risks & Pitfalls
- Download size is not a RAM requirement. GPU memory, Windows commit backing and available system RAM are separate limits.
- Installed is not qualified: an installed Library bundle means component files are present, not that every shared H3 file, node pack or action LoRA is installed.
- A pass validates that outputs exist with bounded dimensions and timing; it is not a creative-quality certificate.
- A guard refusal is not an OOM measurement or proof of a minimum RAM requirement; failed checks are not permanent capacity limits.
- Turning gating off does not remove native prerequisites or live guards (see memory guard and job queue).
- The shared measurements file as fetched covers one hardware configuration only; do not generalise its figures to other machines.
Related Concepts
- install windows rtx spark
- licensing and attribution
- memory guard and job queue
- media library and project files
- picture generation
- loras
- performance and memory
- issues casebook
Sources
raw/github_doc-app-model-catalog-json.md: model ids, labels, groups, download manifests, byte sizes, runtime policies.raw/github_doc-app-model-measurements-json.md: file structure, profile counts, outcomes, representative entries.raw/github_doc-docs-model-measurements-md.md: what goes where, reading rules, sweep commands, check-in steps, download-risk gate.raw/github_doc-docs-windows-md.md: Models & weights behaviour, override flags, Feature checks, uninstall, Hugging Face access.raw/github_doc-readme-md.md: licence statements, gating table, Feature checks summary.raw/github_doc-docs-installation-md.md: Machine โ Models & weights on a Mac and a DGX Spark,app/discover.py --scan.raw/github_doc-docs-moving-an-install-md.md:STUDIO_WINDOWS_FEATURE_DIR, receipts not carried over.raw/github_issue-restore-feature-checks-and-model-availability-diagnostics-wi.md: the Feature checks removal report (#233, closed as completed).raw/github_release-4-4-1-the-4-3-1-screens-are-back.md,raw/github_release-4-5-0-other-machines-as-workers-a-safer-machine-the-library-.md: rollback and return of Feature checks.
