SANA Local Image Generator

Production-oriented local image generation app for NVIDIA SANA / SANA Sprint. It runs on your own Windows PC, Linux GPU server, Docker GPU host, or LAN server without paid image APIs and without fake placeholder output.

The app uses the official NVIDIA SANA repository code from https://github.com/NVlabs/Sana and official Hugging Face repositories under https://huggingface.co/Efficient-Large-Model.

Features

• FastAPI backend with clean endpoints: POST /api/generate, GET /api/history, GET /api/health, GET /outputs/images/{filename}.
• Official SANA Sprint 1.6B 1024px checkpoint support.
• Model loads once on server startup and is reused for every request.
• Single generation lock to avoid concurrent GPU crashes.
• Prompt, negative prompt when the installed pipeline supports it, seed, width, height, steps, and guidance scale controls.
• Local image output in backend/outputs/images/.
• Metadata JSON per generation in backend/outputs/metadata/.
• Plain responsive HTML/CSS/JS frontend served at http://localhost:8000.
• Local-only host binding by default.

Hardware Requirements

• NVIDIA GPU strongly recommended.
• CUDA-capable PyTorch installation.
• 8 GB VRAM can work for optimized SANA variants, but 1024px 1.6B generation is safer with more VRAM.
• CPU fallback is disabled by default because SANA Sprint local CPU inference is usually impractical. Enable only for experimentation with SANA_ALLOW_CPU=true.

Project Structure

image-sana-local/
├── backend/
│   ├── app.py
│   ├── sana_engine.py
│   ├── config.py
│   ├── requirements.txt
│   └── outputs/
│       ├── images/
│       └── metadata/
├── frontend/
│   ├── index.html
│   └── assets/
│       ├── css/style.css
│       └── js/app.js
├── models/
├── scripts/
│   ├── install.sh
│   ├── install.bat
│   ├── run-local.sh
│   ├── run-local.bat
│   └── download-model.py
├── Dockerfile
├── docker-compose.yml
├── README.md
└── .gitignore

Windows Setup

Install prerequisites first:

• Git
• Python 3.10 or 3.11
• NVIDIA driver

Run:

cd image-sana-local
scripts\install.bat

The installer creates .venv, installs CUDA-enabled PyTorch and torchvision from the official PyTorch CUDA index, installs backend requirements, and clones https://github.com/NVlabs/Sana into Sana\ if missing.

Download the official SANA Sprint model:

python scripts\download-model.py

Run the backend:

cd backend
..\.venv\Scripts\activate
uvicorn app:app --host 0.0.0.0 --port 8000

Open:

http://localhost:8000

Windows Fix Commands

Use these exact commands for the current project path:

cd D:\7070\image-ai\image-sana-local
scripts\install.bat
python scripts\download-model.py
cd backend
..\.venv\Scripts\activate
uvicorn app:app --host 0.0.0.0 --port 8000

If scripts\install.bat reports that Python 3.10 or 3.11 is missing, install Python 3.11 first. Python 3.14 is not recommended for CUDA PyTorch/SANA compatibility.

The frontend calls:

http://localhost:8000/api/generate

Linux Setup

Install prerequisites first:

• Git
• Python 3.10 or 3.11
• NVIDIA driver
• CUDA-compatible PyTorch

Run:

cd image-sana-local
bash scripts/install.sh

If needed, install CUDA PyTorch inside the virtual environment:

source .venv/bin/activate
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Download the official SANA Sprint model:

python scripts/download-model.py --model sprint-1.6b-1024

Run locally:

bash scripts/run-local.sh

Equivalent backend command:

cd backend
uvicorn app:app --host 0.0.0.0 --port 8000

Use --host 127.0.0.1 for local-only access. The run scripts default to 127.0.0.1.

Official SANA Repository

The install scripts clone the official NVIDIA repository:

git clone https://github.com/NVlabs/Sana.git Sana

The backend validates these files before loading:

• Sana/app/sana_sprint_pipeline.py
• Sana/configs/sana_sprint_config/1024ms/SanaSprint_1600M_1024px_allqknorm_bf16_scm_ladd.yaml
• models/Sana_Sprint_1.6B_1024px/Sana_Sprint_1.6B_1024px.pth

Update upstream SANA later with:

cd Sana
git pull origin main

Model Download

Automatic download uses official Hugging Face model repositories only:

python scripts/download-model.py --model sprint-1.6b-1024

Supported automatic targets:

• Efficient-Large-Model/Sana_Sprint_1.6B_1024px
• Efficient-Large-Model/SANA1.5_1.6B_1024px_diffusers for manual future extension, not used by default backend generation

Manual placement is also supported:

models/
├── Sana_Sprint_1.6B_1024px/
│   └── Sana_Sprint_1.6B_1024px.pth
├── Sana_1.5/
└── config/

Configuration

Environment variables:

Variable	Default	Purpose
SANA_LOCAL_ONLY	true	Bind locally by default.
SANA_HOST	127.0.0.1	Host for run scripts. Use 0.0.0.0 for LAN.
SANA_PORT	8000	HTTP port.
SANA_REPO_DIR	./Sana	Official cloned SANA repo.
SANA_MODEL_DIR	./models/Sana_Sprint_1.6B_1024px	Model directory.
SANA_CONFIG_PATH	Official Sprint YAML path	SANA Sprint config.
SANA_ALLOW_CPU	false	Allow CPU fallback if you accept very slow inference.
SANA_MAX_STEPS	12	Request limit for steps.
SANA_GENERATION_TIMEOUT	180	Request timeout in seconds.

API Usage

Health:

curl http://localhost:8000/api/health

Generate:

curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a tiny astronaut hatching from an egg on the moon","width":1024,"height":1024,"steps":2,"guidance_scale":4.5,"seed":42}'

History:

curl http://localhost:8000/api/history

Generated images are returned as URLs like:

/outputs/images/sana-sprint-20260515T120000Z-42-abcd1234.png

Docker Deployment

Requires NVIDIA Container Toolkit.

Download the model on the host first:

python scripts/download-model.py --model sprint-1.6b-1024

Run:

docker compose up --build

Open:

http://localhost:8000

LAN Deployment

Local-only is default. To expose on your LAN:

SANA_LOCAL_ONLY=false SANA_HOST=0.0.0.0 bash scripts/run-local.sh

Only do this on a trusted network. This app is not configured for public internet exposure, authentication, or TLS.

AMD Or CPU-Only Machines

SANA Sprint in this project uses the official NVIDIA SANA PyTorch implementation. CUDA acceleration requires an NVIDIA GPU. An AMD GPU on Windows is not a CUDA device, so PyTorch will report torch.cuda.is_available() == False.

You can attempt real CPU fallback with:

cd D:\7070\image-ai\image-sana-local
scripts\run-cpu.bat

CPU fallback is not fake generation, but it can be extremely slow and may require substantial system RAM. AMD GPU acceleration is not enabled by this project because the official SANA repo targets PyTorch CUDA paths, not Windows DirectML.

Security Limits

• Prompt length is limited.
• Negative prompt length is limited.
• Width and height are restricted to 512, 768, or 1024.
• Pixel count and steps are capped.
• Output filenames are generated server-side and sanitized.
• Image serving only allows files from backend/outputs/images/.
• No command execution is exposed through the API.

Troubleshooting

CUDA Not Found

Check:

python -c "import torch; print(torch.cuda.is_available()); print(torch.version.cuda)"

If false, install the CUDA-enabled PyTorch build matching your driver. Example:

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Out Of Memory

Reduce width/height to 768 or 512, reduce steps, close other GPU applications, and keep only one server worker. The app already serializes generation with a lock and clears CUDA cache after generation when configured.

Model Missing

Run:

python scripts/download-model.py --model sprint-1.6b-1024

Then check that this file exists:

models/Sana_Sprint_1.6B_1024px/checkpoints/Sana_Sprint_1.6B_1024px.pth

SANA Repo Missing

Run the installer again or clone manually:

git clone https://github.com/NVlabs/Sana.git Sana

Slow Generation

Use CUDA, keep image size at 1024 or below, keep Sprint steps low, and avoid running multiple uvicorn workers. CPU fallback is not recommended.

Windows Path Issue

Use absolute paths without trailing quotes in environment variables. Example:

set SANA_MODEL_DIR=D:\models\Sana_Sprint_1.6B_1024px

Negative Prompt Not Applied

The backend sends negative_prompt only if the installed official SANA Sprint pipeline exposes that parameter. If the upstream pipeline does not support it, the field is safely ignored.

Notes

This project does not use Stable Diffusion, Flux, SDXL, DALL-E, Midjourney, or any external image generation API. Hugging Face is used only for downloading official SANA model files when requested.