# Diffusers generation examples

These scripts use the Pika H3 Flex Modular Diffusers implementation. Load the base components first, then apply the matching Pika adapter; the base transformer files alone are not Pika-adapted weights.

Use Python 3.12, CUDA-compatible PyTorch, system `git` and `ffmpeg`, and the pinned dependencies in `requirements-diffusers.txt`. The examples use the public Hugging Face Diffusers implementation. See the [official Pika H3 Flex documentation](https://huggingface.co/docs/diffusers/main/en/api/pipelines/pika_h3_flex). Set `HF_TOKEN` if authentication is required to access the model repository.

```bash
python -m pip install huggingface-hub==1.32.0
hf download Pika-Labs/Pika-H3-Flex \
  --include "examples/*" LICENSE NOTICE LICENSE-CODE THIRD_PARTY_NOTICES.md "licenses/*" --local-dir .
python -m pip install -r examples/requirements-diffusers.txt
export MODEL_REPO=Pika-Labs/Pika-H3-Flex
export MODEL_REVISION=$(python -c 'from huggingface_hub import HfApi; print(HfApi().model_info("Pika-Labs/Pika-H3-Flex").sha)')
python examples/generate_fl2va.py --repo "$MODEL_REPO" --revision "$MODEL_REVISION" \
  --resolution 480p --duration 15 --output outputs/cat-cafe-480p.mp4
python examples/generate_ref2va.py --repo "$MODEL_REPO" --revision "$MODEL_REVISION" \
  --resolution 480p --duration 10 --output outputs/record-shop-480p.mp4
```

For 768p, use the following commands. The larger Ref2VA reference sequence needs text/vision encoder offloading on an H100 80 GB; this streams layers from CPU without changing input media or model precision.

```bash
python examples/generate_fl2va.py --repo "$MODEL_REPO" --revision "$MODEL_REVISION" \
  --resolution 768p --duration 15 --output outputs/cat-cafe-768p.mp4
python examples/generate_ref2va.py --repo "$MODEL_REPO" --revision "$MODEL_REVISION" \
  --resolution 768p --duration 10 --text-encoder-offload --output outputs/record-shop-768p.mp4
```

The cat-cafe example uses one first frame and the FL2VA adapter. It does not supply a last frame. The record-shop example uses character and environment images followed by a motion-reference video, including its audio. Prompts are passed verbatim. Assets are read from `examples/assets/` or downloaded from the same pinned HF revision when missing.

Both examples generate a 16:9 canvas: 832×480 at 480p or 1344×768 at 768p. Frame counts follow the model's 17n+5 grid, so 15 seconds produces 362 frames and 10 seconds produces 243 frames, at 24 fps. Each result contains mixed stereo audio at 32 kHz. The scripts check the encoded media and write timing, geometry, hashes and peak GPU allocation to a JSON file next to the MP4.

The examples move components between CPU and GPU and stream transformer blocks from host memory by default. Plan for at least 256 GB of available host RAM per request, including loading and pinned-memory headroom, plus disk space: the complete repository adds approximately 210 GB of base components, though a selected workflow loads only its transformer partition. Use `--resident-transformer` only if the GPU has enough memory. `--snapshot` can point to a complete local copy of the specified revision; `--assets-dir` can point to a separate directory containing `fl2va/` and `ref2va/` inputs.

Supporting code is pinned to the public Diffusers commit `d0b9b1b5a540e5f9df2f8ec236347bf9c5aa7d1f`, which reports `0.42.0.dev0`.

The following results are from the previously validated development revision, before this documentation/dependency update; inference was not rerun for the public upstream pin.

Validation used one H100 80 GB per request, Python 3.12 and PyTorch 2.13.0 with CUDA 12.9. All four cases passed encoded-video, frame-count and stereo-audio checks; sampled frames were also inspected.

| Example | Output | Frames | Encoder layer offload | Peak GPU allocation |
| --- | --- | --- | --- | --- |
| FL2VA first frame | 832×480 | 362 | No | 72.2 GiB |
| Ref2VA image/video references | 832×480 | 243 | No | 71.2 GiB |
| FL2VA first frame | 1344×768 | 362 | No | 72.2 GiB |
| Ref2VA image/video references | 1344×768 | 243 | Yes | 44.9 GiB |

The 768p tests loaded the preparation model snapshot through the Hub; the official release preserves those tensor contents. Initial 480p tests used the contributed checkpoint revision before metadata-only license packaging; all rewritten tensor payloads were verified unchanged. The 768p Ref2VA case exceeded H100 memory without `--text-encoder-offload`, so retain that flag for this example. These are functional checks, not optimized speed benchmarks or a guarantee that every input combination fits the same hardware. CPU offload trades speed for memory; full runs can take several minutes.