Documentation

Setup

01 · Installation
02 · Python Environment
03 · Downloading Models
04 · Cloud API Keys

Usage

05 · Object Tab (Texture)
06 · World Tab (HDR)
07 · 3D Tab (Mesh)
08 · Gallery · Troubleshooting · FAQ

01

Installation

Windows only. Blender 4.0 or newer required. The addon folder is installed to your Blender scripts/addons directory — no admin rights needed.

02

Python Environment

What gets installed

Environment location: Stored in your Blender extensions folder, not inside the addon itself. Deleting the addon folder does not delete the environment. You can delete it manually from Preferences.

03

Downloading Models

FLUX.1 Dev note: Requires accepting a license on huggingface.co before downloading. Set your HF token in Preferences under HuggingFace, then accept the license on the model page. FLUX.1 Schnell (Apache 2.0) needs no token.

04

Cloud API Keys

HuggingFace + image generation: Set the inference provider to fal-ai — not hf-inference. As of July 2025, hf-inference no longer supports image generation. fal-ai and replicate use the same HF token.

05

Object Tab — Texture Generation

06

World Tab — HDR Environment

07

3D Tab — Mesh Generation

Cloud 3D recommended for most users. Meshy text→3D takes ~60s (preview + texture). Tripo takes ~10-30s. Both produce better geometry and textures than most local models. Local models require significant VRAM and are slower on consumer GPUs.

08

Gallery

Apply to Object

Applies the selected texture generation to the active object as a full PBR material.

Set as World

Shown for world/HDR entries. Applies the selected panorama as the scene world (rebuilds the world node tree).

Import 3D Model

Shown for 3D mesh entries. Imports the .glb file as a new mesh object, selects and activates it.

Texture Scale

Set a scale multiplier and click Apply to update the Mapping node Scale on the active material. Values >1 tile more, <1 stretch more.

Delete

Permanently removes the generation, its files on disk, and its gallery entry. This cannot be undone.

09

Troubleshooting

Environment says "ready" but models run on CPU

The environment was set up before the CUDA torch fix. Click Reinstall with GPU Support in Preferences. This rebuilds the venv with the proper CUDA PyTorch wheel from download.pytorch.org.

CUDA out of memory

Close other GPU-heavy applications. Check the model's VRAM requirement against your available VRAM. The addon shows a warning before generation if free VRAM is below the model's minimum. Try a lighter model (DreamShaper 8 at 4 GB instead of SDXL at 10 GB).

Could not delete environment — Access denied

A Python process is still running in the venv. Open Task Manager, end any python.exe processes, then try reinstalling. The addon also attempts to kill these automatically via taskkill.

Shap-E fails with "Access is denied: shap_e_model_cache"

Shap-E tries to cache weights in the current working directory (Blender's install folder — read-only). The addon patches this automatically. If it still occurs, ensure you are on the latest addon version.

HuggingFace cloud returns HTTP 410 or HTTP 400

Set the inference provider to fal-ai, not hf-inference. As of July 2025 hf-inference does not support text-to-image for modern models. The panel shows a warning when hf-inference is selected with an incompatible model.

3D model generated but nothing appears in the viewport

Check the System Console (Window → Toggle System Console) for the import error. The addon needs a 3D Viewport area open to resolve the correct import context. Ensure the 3D Viewport is visible (not minimised) when generating.

Panel shows "Checking environment…" on every startup

This is normal. On startup the addon runs a background subprocess check (imports torch, diffusers, etc.) to verify the environment is intact. It takes 5-30 seconds depending on your machine. The full Getting Started checklist only appears if the check confirms the environment is missing or broken.

No Mapping node found — texture scale not working

The Texture Scale control looks for a Mapping node in the active material. This is created automatically when you apply a generated texture through the addon. If you applied the texture manually or through another addon, add a Mapping node to the material's node tree manually.

10

FAQ

Can I use this on a laptop?

Yes, if your laptop has an Nvidia GPU with 4+ GB VRAM. Smaller models like DreamShaper 8 or Shap-E run comfortably on 4-6 GB. For laptops without a dedicated GPU, use the Cloud API providers — no local GPU required.

Do I need internet to use offline models?

Only for the initial download. Once downloaded, local models run completely offline. No data is sent anywhere during generation. Cloud APIs always require internet.

Can I use the generated textures commercially?

It depends on which model generated them. FLUX.1 Schnell (Apache 2.0), StableMaterials (Apache 2.0), DreamShaper 8, and most SDXL models are commercially usable. FLUX.1 Dev has a non-commercial dev license. Check each model's license on HuggingFace before commercial use. Cloud API outputs are subject to each provider's terms of service.

Why does the first generation on startup take longer?

The first time a model is used in a session, PyTorch loads the weights from disk into VRAM and compiles any CUDA kernels. This can take 1-3 minutes. Subsequent generations in the same session are much faster.

Where are generated files stored?

All outputs are saved in your Blender extensions folder under kretos_ai_gen_output/. Each generation gets a timestamped subfolder containing the PNG maps and a JSON metadata file used by the gallery.

Can I use Replicate to access models not in the default list?

Yes. In Preferences → Replicate, enter any model as owner/name in the Custom Model ID field (e.g. stability-ai/sdxl). This overrides the dropdown. The model must accept a prompt input and return an image URL.

How do I report a bug?

Report through the product page where you purchased the addon. Include: what you were doing, the exact error message from the Info bar, your GPU and VRAM, Blender version, and the output from Window → Toggle System Console if available. We read and respond to every report.

⚠ Beta — v2.1.0

Kratos Blender AI is in active development. Core functionality works but you may encounter bugs, model-specific quirks, or edge cases. Every bug report directly improves the addon.

When reporting, include:

Report through the product page where you purchased this addon.

KretosAI

Documentation · v2.1.0 Beta · Windows

Compatible with Blender 4.0+ · Windows only
This addon is in beta — bug reports welcome and appreciated.
© 2025 All rights reserved.