This release is a pre-release and may not be stable for production use.
Z-Vision Generator
Local AI image and video generation — hassle-free and fun. No tangled node graphs, no cloud dependencies, just prompts and results. Runs on macOS (Apple Silicon / MLX) and on Windows and Linux with NVIDIA CUDA through diffusers.
Features
- Image generation — text-to-image with Z-Image, FLUX.2 Klein (4B/9B) and Krea 2 Turbo model families, plus Ideogram 4 (FP8 on macOS/MLX, NF4 on Windows and Linux)
- Video generation — text-to-video and image-to-video with platform-specific LTX aliases across macOS, Windows, and Linux
- Cross-platform — automatic backend selection: MLX on macOS, diffusers/CUDA on Windows and Linux for images, and the shared diffusers/CUDA LTX backend on Windows and Linux for video
- Prompt system — YAML prompt files with variables, structured prompts, snippets, and batch runs
- Model store — central
~/.ziv/directory with bare-name resolution and HuggingFace fallback - LoRA support — single or stacked, configurable weights, bare-name resolution
- Image upscale — generate small → Lanczos → img2img refine → CAS sharpen
- Video upscale —
--upscale 2renders at half size, upsamples the latents 2× and refines at full size, so the clip keeps the requested size, on macOS and on Windows/Linux - Reference images — img2img steering from any starting image
- Model variants — image quantization across supported image backends, plus macOS MLX video Q4/Q8 aliases
- Post-processing — contrast, saturation, and CAS sharpening (image only)
- Interactive controls — skip, quit, pause, and repeat during image batch runs; Web UI video jobs can be cancelled
Platform Support
| Platform | Image Generation | Video Generation |
|---|---|---|
| macOS (Apple Silicon) | ✅ Z-Image / FLUX / Krea 2 / Ideogram 4 via mflux/MLX | ✅ LTX via MLX aliases (ltx-4, ltx-8) |
| Windows (NVIDIA GPU) | ✅ Z-Image / FLUX / Krea 2 / Ideogram 4 via diffusers/CUDA | ✅ LTX via diffusers/CUDA aliases (ltx-4, ltx-8) |
| Linux (NVIDIA GPU) | ✅ Z-Image / FLUX / Krea 2 / Ideogram 4 via diffusers/CUDA | ✅ LTX via diffusers/CUDA aliases (ltx-4, ltx-8) |
Installation
Requires Python 3.14+ and uv.
uv is required. This package cannot be installed with pip — some dependencies require uv-specific resolution that pip does not support. All commands below use uv.
# Install globally from PyPI
uv tool install z-vision-generator
# Install globally from repository
uv tool install -e git+https://github.com/knuthelge/ZVisionGenerator.git
# Development setup
git clone https://github.com/knuthelge/ZVisionGenerator && cd ZVisionGenerator
uv sync
Video generation requires ffmpeg. On Windows and Linux, image and video generation require an RTX 20-series (Turing) or newer NVIDIA GPU, including RTX 50-series, with NVIDIA driver 580 or newer, so that CUDA is available to PyTorch.
Video uses
ltx-4(4-bit) orltx-8(8-bit) on every platform. On Windows and Linux they need about 20 GB and 27 GB of system memory. See the Video Guide.
Quick Start
# Generate an image (bare name from ~/.ziv/models/)
ziv-image -m my-model --prompt "a beautiful sunset"
# Generate from a HuggingFace model
ziv-image -m Tongyi-MAI/Z-Image-Turbo --prompt "a cat in a garden"
# Batch run from a prompts file
ziv-image -m my-model -p prompts.yaml -r 3
# Generate a video (4-bit LTX)
ziv-video -m ltx-4 --prompt "A cat walking through a garden"
# Image-to-video
ziv-video -m ltx-4 --image photo.jpg --prompt "Camera zooms in slowly"
# Launch the Web UI
ziv ui
# Show command help and available subcommands
ziv
The Web UI is an explicit local launcher: use ziv ui or ziv-ui. Running bare ziv prints command-discovery help without starting a browser or server. If a local environment is missing required Web UI packages, the launcher reports how to repair the base install instead of failing with an import traceback.
The packaged Web UI is served from local static files and does not fetch cloud fonts or other font assets at runtime. It uses local system font fallbacks when Inter or JetBrains Mono are not installed.
Tip:
ziv image,ziv video, andziv modelare also available as subcommands of the unifiedzivparent command. Useziv -horziv --helpto print terminal help.
Documentation
Full documentation is available at knuthelge.github.io/ZVisionGenerator.
- Getting Started — installation, model store, quick start
- Image Guide — aliases, sizes, reference images, LoRA, upscaling, quantization
- Video Guide — T2V, I2V, upscale, audio, LoRA, constraints
- Prompts Guide — prompt files, variables, structured prompts, snippets
- Model & LoRA Guide — checkpoint conversion, LoRA import, asset listing
- CLI Reference — full argument tables for all commands
- Development — setup, testing, architecture
Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines.
License
This project is licensed under the GNU Affero General Public License v3.0 or later.
Metadata
Release files for z-vision-generator 0.13.0b25
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| z_vision_generator-0.13.0b25.tar.gz | 3.8 MB | With provenance | Details for z_vision_generator-0.13.0b25.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| z_vision_generator-0.13.0b25-py3-none-any.whl | Python 3 | none | any | Details for z_vision_generator-0.13.0b25-py3-none-any.whl |
Total release size: 6.3 MB
Release files / z_vision_generator-0.13.0b25.tar.gz
| Download URL | z_vision_generator-0.13.0b25.tar.gz |
|---|---|
| Size | 3.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef131212f9cb6fd35a0853be385326b4f355b584d7e600b3b20e876bc628ff3a
|
|
BLAKE2b-256 checksum How to use checksums |
0d9f3a6f1f34ec7598a4cdd3a345efc6e97c28bd9d952587cf68d70220aa06ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / z_vision_generator-0.13.0b25-py3-none-any.whl
| Download URL | z_vision_generator-0.13.0b25-py3-none-any.whl |
|---|---|
| Size | 2.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cba6f37bbff51b50686e4e6dc95910f488edf82f5e1f908eab20c1c2be4f10cf
|
|
BLAKE2b-256 checksum How to use checksums |
e687a3494a89c14f6fdd76884c7dc7e63a2c188002400db0eab51cdfb4a3ef61
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for z-vision-generator 0.13.0b25
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for z_vision_generator-0.13.0b25.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.