Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

 

Z-Vision Generator logo with the Blob mascot

 

Z-Vision Generator

CI PyPI Python 3.14+ License: AGPL-3.0

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 and FLUX.2 Klein (4B/9B) model families, plus Ideogram 4 (FP8) on macOS/MLX
  • 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 — 2× spatial upscaling through the platform LTX backend when supported by the selected runtime
  • 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 batch runs (image only)

Platform Support

Platform Image Generation Video Generation
macOS (Apple Silicon) ✅ Z-Image / FLUX / Ideogram 4 via mflux/MLX ✅ LTX via MLX aliases (ltx-4, ltx-8)
Windows (NVIDIA GPU) ✅ Z-Image / FLUX via diffusers/CUDA ✅ LTX via diffusers/CUDA alias (ltx-2.3)
Linux (NVIDIA GPU) ✅ Z-Image / FLUX via diffusers/CUDA ✅ LTX via diffusers/CUDA alias (ltx-2.3)

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 NVIDIA GPU with CUDA available to PyTorch.

The packaged Windows/Linux ltx-2.3 alias defaults to the configurable diffusers-converted repository dg845/LTX-2.3-Diffusers. This is the diffusers-compatible layout required by the Windows/Linux video backend, not an official Lightricks alias. Override it in ~/.ziv/config.yaml if you want to point ltx-2.3 at a different compatible diffusers repository.

The macOS video aliases ltx-4 and ltx-8 are the shipped MLX Q4/Q8 presets. Windows and Linux use the diffusers-backed ltx-2.3 alias instead, so the Q4/Q8 naming does not carry across platforms.

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 on macOS
ziv-video -m ltx-4 --prompt "A cat walking through a garden"

# Generate a video on Windows or Linux
ziv-video -m ltx-2.3 --prompt "A cat walking through a garden"

# Image-to-video on macOS
ziv-video -m ltx-4 --image photo.jpg --prompt "Camera zooms in slowly"

# Image-to-video on Windows or Linux
ziv-video -m ltx-2.3 --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, and ziv model are also available as subcommands of the unified ziv parent command. Use ziv -h or ziv --help to print terminal help.

Documentation

Full documentation is available at knuthelge.github.io/ZVisionGenerator.

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.0b5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for z-vision-generator 0.13.0b5
File Size Uploaded Provenance Actions
z_vision_generator-0.13.0b5.tar.gz 1.0 MB With provenance Details for z_vision_generator-0.13.0b5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for z-vision-generator 0.13.0b5
File Interpreter ABI Platform Actions
z_vision_generator-0.13.0b5-py3-none-any.whl Python 3 none any Details for z_vision_generator-0.13.0b5-py3-none-any.whl

Total release size: 1.5 MB

Release files / z_vision_generator-0.13.0b5.tar.gz

Download URL z_vision_generator-0.13.0b5.tar.gz
Size 1.0 MB
Tags Source
SHA-256 checksum
How to use checksums
7fce3e37be701913cfc9c89e799c4a4ac2c69e752accc1a763df19e0c9e2ea6f
BLAKE2b-256 checksum
How to use checksums
7252324a7ea236c6fb13e7cbf97c4dab6ba89f8619d91be1f47e85eeb0622550
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 3, 2026.

Transparency log

Release files / z_vision_generator-0.13.0b5-py3-none-any.whl

Download URL z_vision_generator-0.13.0b5-py3-none-any.whl
Size 490.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2b5c08ac4bb0bb953fe91cfdec259e82e3a14acde0a4e4cb13c6143e53418a66
BLAKE2b-256 checksum
How to use checksums
1cdae4fc85fc203dc7deab1fbdd00a3a13c8be31f8bf97318a6208652ba492a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 3, 2026.

Transparency log

Security for z-vision-generator 0.13.0b5

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.

Select from 2 files

Attestation for z_vision_generator-0.13.0b5.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 3, 2026.

Transparency log

A 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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page