README.md

---
license: apache-2.0
library_name: mlx
base_model: ByteDance-Seed/SeedVR2-7B
tags:
  - mlx
  - mflux
  - mlx-swift
  - super-resolution
  - image-upscaling
  - diffusion
  - apple-silicon
pipeline_tag: image-to-image
---

# SeedVR2-7B (MLX) — fp16

Runtime-agnostic **MLX-format** weights (fp16) for **SeedVR2-7B**, ByteDance's one-step diffusion **super-resolution / restoration** model (ICLR 2026), for on-device upscaling on Apple Silicon.

Not tied to any single package — these load into:
- [`mflux`](https://github.com/filipstrand/mflux) (Python MLX, actively maintained; also the parity reference these weights were validated against),
- [`seedvr2-mlx-swift`](https://github.com/xocialize/seedvr2-mlx-swift) (MLX-Swift; **archived/read-only since Jun 2026** but functional — MIT-licensed and forkable),
- or any MLX code that reconstructs the same module tree (see **Format notes** below).

int8 variant: [`SeedVR2-7B-mlx-int8`](https://huggingface.co/benc0/SeedVR2-7B-mlx-int8) · sharp checkpoint: [`SeedVR2-7B-sharp-mlx`](https://huggingface.co/benc0/SeedVR2-7B-sharp-mlx) · 3B family: [`mlx-community/SeedVR2-3B-mlx`](https://huggingface.co/mlx-community/SeedVR2-3B-mlx)

- **Files:** `transformer.safetensors` (DiT, fp16, ~16.5 GB) · `vae.safetensors` (3D-causal-conv VAE, fp16) · `pos_emb.safetensors` (precomputed text embedding, 58×5120) · `config.json`.
- **Architecture (vs 3B):** vid_dim 3072 (2560), 24 heads (20), 36 layers (32), all layers multimodal, plain MLP (SwiGLU), rope_dim 64.
- **Precision:** fp16. Transformer reload vs the mflux reference (CPU): `t_out` max_abs **0.00e+00 (bit-exact)**. End-to-end GPU vs CPU pipeline: 60 dB PSNR.
- **Memory:** ~17 GB weights resident; recommended 32 GB+ unified memory (below that, use the int8 variant).

## Usage — Python (MLX / mflux)

```python
import json, mlx.core as mx
from mlx.utils import tree_unflatten
from mflux.models.seedvr2.model.seedvr2_transformer.transformer import SeedVR2Transformer

cfg = json.load(open("config.json"))
tx = SeedVR2Transformer(**cfg["transformer_overrides"])
tx.update(tree_unflatten(list(mx.load("transformer.safetensors").items())))
mx.eval(tx.parameters())   # bit-exact vs the mflux reference (verified at export)
```

The full pipeline (VAE, scheduler, pre/post-processing) lives in mflux: `mflux-upscale-seedvr2 --model seedvr2-7b --image-path input.png --resolution 2x` (note: mflux's built-in downloader fetches the PyTorch source weights and converts on the fly; loading *these* pre-converted files uses the snippet above).

## Usage — Swift

```swift
import SeedVR2MLX   // github.com/xocialize/seedvr2-mlx-swift (archived/read-only, MIT — fork to maintain)
let upscaler = try SeedVR2Upscaler(directory: weightsDir)   // downloaded from this repo
let out = upscaler.upscale(processedImage: img, seed: 42)   // [-1,1], dims padded to /16
```

## Format notes (for other MLX runtimes)

- **Key naming:** mflux module hierarchy, flattened with `mlx.utils.tree_flatten` (e.g. `blocks.17.attn.proj_qkv_vid.weight`). Deterministic mapping back to ByteDance's original PyTorch names: mflux `src/mflux/models/seedvr2/weights/seedvr2_weight_mapping.py`.
- **Layouts:** MLX conventions throughout — VAE conv weights are `(O, *K, I)`.
- **Config:** `config.json["transformer_overrides"]` carries the 7B dims (vid_dim 3072, heads 24, num_layers 36, mm_layers 36, rope_dim 64, …) and must be passed to the transformer constructor.
- **Conditioning:** `pos_emb.safetensors` (58×5120, fp16) is the precomputed embedding of the fixed prompt — the text encoder is eliminated from this port, so it is a mandatory `txt` input.

## Provenance & license

Chain: **ByteDance Seed** — *SeedVR2: One-Step Video Restoration via Diffusion Adversarial Post-Training* (ICLR 2026, [arXiv:2506.05301](https://arxiv.org/abs/2506.05301)), [ByteDance-Seed/SeedVR](https://github.com/ByteDance-Seed/SeedVR), **Apache-2.0** → PyTorch fp16 redistribution [`numz/SeedVR2_comfyUI`](https://huggingface.co/numz/SeedVR2_comfyUI) (`seedvr2_ema_7b_fp16.safetensors`; independently verified **bitwise** against ByteDance's original fp32 `seedvr2_ema_7b.pth` — all 1128 tensors identical after fp32→fp16 cast) → MLX reference impl [`filipstrand/mflux`](https://github.com/filipstrand/mflux) → export via [`xocialize/seedvr2-mlx`](https://github.com/xocialize/seedvr2-mlx) tooling. These are format-converted weight artifacts (not a new model); Apache-2.0 applies. Credit ByteDance Seed (original), cite the paper.