Skip to main content

imagehub — one API for open text-to-image models. The input "a photograph of an astronaut riding a horse" passes through a small neural network, and the output switches between images from different open models.

Open-weight text-to-image architectures in native PyTorch.

imagehub provides one API for open-weight text-to-image architectures using native PyTorch reimplementations; PyTorch is the only required runtime dependency. CPU float32 outputs are bit-identical to the reference implementations; see validation. It supports Python 3.11 and later.

Install

pip install imagehub            # torch only
pip install "imagehub[image]"   # adds Pillow for Image.to_pil()

Quickstart

python -m imagehub.pretrained sd-v1-5 checkpoints/sd-v1-5
from imagehub import pipeline

with pipeline("t2i", backend="sd-v1-5", model="checkpoints/sd-v1-5") as pipe:
    result = pipe("a photograph of an astronaut riding a horse", seed=42)
result.images[0].save("astronaut.png")
print(result.metadata)

Most models accept text alone. Some also accept an optional image= input for image-conditioned generation or editing.

from PIL import Image
with pipeline("t2i", backend="flux1-kontext-dev", model="checkpoints/flux1-kontext-dev") as edit:
    result = edit("Add a red hat to the scene", image=Image.open("photo.png"), seed=0)
result.images[0].save("edited.png")

LoRA adapters load on the Stable Diffusion 1.x and 2.x, SDXL, SD3, FLUX.1, FLUX.2 klein, Sana, Qwen-Image, Z-Image, Lumina 2, HiDream-I1, Krea 2 and Ideogram 4 backends (details):

with pipeline("t2i", backend="sd-v1-5", model="checkpoints/sd-v1-5",
              lora="style.safetensors", lora_scale=0.8) as pipe:
    result = pipe("a watercolor fox", seed=0)

Train

pip install "imagehub[training]"
from imagehub.training import ImageFolderDataset, Trainer, TrainingArguments

trainer = Trainer(
    model="sd-v1-5",
    checkpoint="checkpoints/sd-v1-5",
    args=TrainingArguments(output_dir="runs/my-dog", max_steps=1000),
    train_dataset=ImageFolderDataset("my_images"),  # images + metadata.jsonl
)
trainer.train()
trainer.save_model("runs/my-dog/final")  # load it back with lora=".../adapter.safetensors"

LoRA training covers Stable Diffusion 1.x and 2.x, SDXL and its fine-tunes, SD3 and 3.5, FLUX.1, FLUX.2 klein, Sana, Qwen-Image, Z-Image, Lumina 2, HiDream-I1 and Krea 2. The training guide lists every trainable checkpoint.

Models

The model catalog lists every supported checkpoint with its source, pinned revision, and license. Creating a pipeline for a checkpoint without commercial-use rights emits an ImageHubLicenseWarning, which standard Python warning filters can silence. The former ImagehubLicenseWarning spelling remains an alias.

All model families
Family Checkpoints Task Input Validation
Latent Diffusion Model ldm-text2im-large-256 t2i T CPU fp32 parity
Stable Diffusion sd-v1-1, sd-v1-2, sd-v1-3, sd-v1-4, sd-v1-5, dreamshaper-8, segmind-small-sd, segmind-tiny-sd, bk-sdm-base, bk-sdm-small, bk-sdm-tiny, bk-sdm-v2-base, bk-sdm-v2-small, bk-sdm-v2-tiny, sd-v2-1, sd-turbo, sdxs-512-0.9, lcm-dreamshaper-v7 t2i T CPU fp32 parity (segmind-tiny-sd on the upcast float16 weights)
Stable Diffusion XL sdxl-base-1.0, sdxl-lightning-2step, sdxl-lightning-4step, sdxl-lightning-8step, hyper-sdxl-1step, dmd2-sdxl-4step, dmd2-sdxl-1step, sdxl-turbo, ssd-1b, segmind-vega, koala-700m, koala-1b, koala-lightning-700m, koala-lightning-1b, playground-v2, playground-v2.5, juggernaut-xl-v9, animagine-xl-4.0, dreamshaper-xl-1.0 t2i T CPU fp32 parity (Juggernaut and Animagine on upcast float16 weights)
Stable Diffusion XL refiner sdxl-refiner-1.0 t2i T, I CPU fp32 parity
Stable Diffusion 3 and 3.5 sd3-medium, sd3.5-medium, sd3.5-large, sd3.5-large-turbo t2i T CPU fp32 parity
DreamLite dreamlite-base, dreamlite-mobile t2i T, I CPU fp32 parity on the upcast bfloat16 weights
JoyAI-Image joyai-image-edit, joyai-image-edit-plus t2i T, I CPU fp32 parity on the upcast bfloat16 weights
Cosmos-Predict2 cosmos-predict2-2b-t2i t2i T CPU fp32 parity on the upcast bfloat16 weights
FLUX.1 flux1-schnell, flux1-dev, flux1-krea-dev, flux-1-lite-8b t2i T CPU fp32 parity on the upcast bfloat16 weights
FLUX.1 Kontext flux1-kontext-dev t2i T, I CPU fp32 parity
VisualCloze visualcloze-384 t2i T, I CPU fp32 parity
FLUX.2 flux2-klein-4b, flux2-klein-9b t2i T CPU fp32 parity
HunyuanDiT hunyuan-dit-v1.1-distilled, hunyuan-dit-v1.2, hunyuan-dit-v1.2-distilled t2i T CPU fp32 parity
DeepFloyd IF deepfloyd-if-i-xl t2i T CPU fp32 parity
Kandinsky 2.1 kandinsky-2-1 t2i T CPU fp32 parity
Kandinsky 2.2 kandinsky-2.2 t2i T CPU fp32 parity
Kandinsky 3 kandinsky-3 t2i T CPU fp32 parity on the upcast float16 weights
Kandinsky 5 kandinsky-5-t2i-lite t2i T CPU fp32 parity
Stable Cascade stable-cascade, stable-cascade-lite t2i T CPU fp32 parity
Würstchen v2 wuerstchen-v2 t2i T CPU fp32 parity
PixArt pixart-sigma-xl-1024, pixart-sigma-xl-512, pixart-sigma-xl-256, pixart-sigma-xl-2k, pixart-alpha-xl-1024, pixart-alpha-xl-512, pixart-lcm-xl-1024 t2i T CPU fp32 parity
Sana sana-1600m-1024, sana-600m-1024, sana-sprint-1.6b-1024, sana-1.5-4.8b-1024 t2i T CPU fp32 parity
Kolors kolors t2i T CPU fp32 parity on the upcast float16 weights
Lumina-Image 2.0 lumina-image-2.0 t2i T CPU fp32 parity
Lumina-Next lumina-next t2i T CPU fp32 parity
Lumina-DiMOO lumina-dimoo t2i T CPU fp32 parity on the upcast bfloat16 weights
OmniGen omnigen-v1 t2i T, I CPU fp32 parity on the upcast bfloat16 transformer
Ovis-Image ovis-image-7b t2i T CPU fp32 parity on the upcast bfloat16 VAE weights
aMUSEd amused-256, amused-512 t2i T CPU fp32 parity
Meissonic meissonic t2i T CPU fp32 parity
AuraFlow auraflow-v0.3 t2i T CPU fp32 parity
PRX prx-1024-t2i-beta, prx-512-t2i-sft t2i T CPU fp32 parity on the upcast bfloat16 text encoder
Chroma chroma1-hd, chroma1-flash, chroma1-base t2i T CPU fp32 parity on the upcast bfloat16 weights
LlamaGen llamagen-t2i-xl-256, llamagen-t2i-xl-512 t2i T CPU fp32 parity
Infinity infinity-2b t2i T CPU fp32 parity; 256px shortened validation run
HART hart t2i T CPU fp32 parity on the upcast bfloat16 text encoder
Show-o show-o-512 t2i T CPU fp32 parity
Emu3 emu3-gen t2i T CPU fp32 parity with shortened 24×16 end-to-end runs
NextStep-1 nextstep-1-large t2i T CPU fp32 parity on the upcast bfloat16 weights
PixelDiT pixeldit t2i T CPU fp32 parity; code is NSCLv1, non-commercial
Krea 2 krea2-turbo t2i T CPU fp32 parity
Nucleus-Image nucleus-image t2i T CPU fp32 parity on the upcast bfloat16 weights
ERNIE-Image ernie-image t2i T CPU fp32 parity without the prompt enhancer
LongCat-Image longcat-image t2i T CPU fp32 parity
HunyuanImage 2.1 hunyuanimage-2-1 t2i T CPU fp32 parity
CogView3-Plus cogview3-plus-3b t2i T CPU fp32 parity on the upcast bfloat16 transformer and VAE
CogView4 cogview4-6b t2i T CPU fp32 parity
GLM-Image glm-image t2i T CPU fp32 parity
Ideogram 4 ideogram4-fp8 t2i T CPU fp32 parity with the official implementation
Qwen-Image qwen-image, qwen-image-2.1 t2i T CPU fp32 parity on the upcast bfloat16 weights
Qwen-Image-Edit qwen-image-edit, qwen-image-edit-2509 t2i T+I CPU fp32 parity on the upcast bfloat16 weights, shortened 32×32 end-to-end runs
Z-Image z-image, z-image-turbo t2i T CPU fp32 parity
Janus-Pro janus-pro-1b, janus-pro-7b t2i T CPU fp32 parity
BAGEL bagel-7b-mot t2i T CPU fp32 parity on the upcast bfloat16 weights
HiDream-I1 hidream-i1-dev, hidream-i1-fast, hidream-i1-full t2i T CPU fp32 parity on the upcast bfloat16 and float16 weights
HiDream-O1 hidream-o1-image t2i T CPU fp32 parity

Validation

Every listed checkpoint is validated against its reference implementation, with CPU float32 image outputs required to match bit-for-bit. The validation documentation describes the coverage and recorded results.

Documentation

Documentation site · Model catalog · Model architecture notes · Validation · Changelog · Third-party notices

Development

uv venv -p 3.13 .venv && uv pip install --python .venv -e ".[dev,image]"
.venv/bin/python scripts/fetch_fixtures.py
.venv/bin/python -m pytest

Some published configuration and tokenizer fixtures retain checkpoint-specific license terms and are fetched into the ignored tests/fixtures/_restricted cache. Set HF_TOKEN before running the fetcher to include gated repositories; tests for unavailable fixtures skip with the same command.

Reference comparisons are optional; install .[dev,image,reference] and run IMAGEHUB_REFERENCE_TESTS=1 .venv/bin/python -m pytest tests/reference with local checkpoint paths configured. A few of them import the authors' original code; point IMAGEHUB_REFERENCE_SOURCES at a folder of those checkouts (default checkpoints/ref-src), and the tests skip when a checkout is missing.

The documentation site builds with the pinned versions in the docs extra:

uv pip install --python .venv -e ".[docs]"
.venv/bin/mkdocs build --strict

License

The project is Apache-2.0 overall. Clearly marked third-party derivatives retain their own license; in particular, the PixelDiT source is NSCLv1 and non-commercial. Each checkpoint also has its own license; see the model catalog, NOTICE, and third-party notices.

Roadmap

Planned work after the first release:

  • LoRA adapter loading for inference — #193
  • Training support: LoRA fine-tuning as imagehub[training] — #194
  • GPU and half-precision validation — #195
  • More model families — #11

Metadata

Release files for imagehub 0.1.0

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

Source distribution (sdist)

Source distribution for imagehub 0.1.0
File Size Uploaded Provenance Actions
imagehub-0.1.0.tar.gz 34.4 MB With provenance Details for imagehub-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for imagehub 0.1.0
File Interpreter ABI Platform Actions
imagehub-0.1.0-py3-none-any.whl Python 3 none any Details for imagehub-0.1.0-py3-none-any.whl

Total release size: 35.2 MB

Release files / imagehub-0.1.0.tar.gz

Download URL imagehub-0.1.0.tar.gz
Size 34.4 MB
Tags Source
SHA-256 checksum
How to use checksums
f4271a82b86995653fc17526168147d1250cf565b5fbb14962f3bb6e13893e43
BLAKE2b-256 checksum
How to use checksums
1eab512a9f35ced1a48aaceb34d7f8d330b53a59ebafd9fc6f68aaaad93dc3a1
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 Nov 15, 2026.

Transparency log

Release files / imagehub-0.1.0-py3-none-any.whl

Download URL imagehub-0.1.0-py3-none-any.whl
Size 857.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5b6eb6b70a4336d181a2638d498bb15069a4ba95dc63500d803780a9762ed484
BLAKE2b-256 checksum
How to use checksums
49719c97184f59fc859add8dafb2bbac45cd7df1782263e338cc853475f9c8b5
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 Nov 15, 2026.

Transparency log

Security for imagehub 0.1.0

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 imagehub-0.1.0.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 Nov 15, 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

0.1.0 This release

2 release files Full provenance

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