100% Full API Reference Manual
Comprehensive public interface specification for termux_diffusion (Python) and termux-diffusion (Node.js).
1. generate(...) - Main Image Generation Function
| Parameter |
Type |
Default |
Description |
prompt |
str |
(Required) |
Text description of the desired visual image. |
negative_prompt |
str | None |
None |
Unwanted visual traits (e.g. "blurry, bad anatomy, deformed"). |
model |
str |
"realistic" |
Preset name ("realistic", "speed", "sdxs", "turbo", "anime"), HuggingFace repo/file, or local .gguf path. |
device |
str |
"cpu" |
Compute target: "cpu", "gpu", "opencl", or "vulkan". |
output |
str | Path | None |
None |
Destination output image file path (e.g. "output.png"). |
width |
int |
512 |
Image width in pixels (must be a multiple of 64). |
height |
int |
512 |
Image height in pixels (must be a multiple of 64). |
steps |
int |
10 |
Number of denoising diffusion steps (optimal: 10 for Q4_K, 2 for sdxs, 1 for turbo). |
cfg_scale |
float |
4.0 |
Classifier-Free Guidance scale (optimal: 4.0 for quantized weights). |
negative_prompt |
str | None |
None |
Optional negative guidance describing elements to avoid (default: None for pure prompt fidelity). |
seed |
int |
-1 |
Random number generator seed (-1 for randomized seed). |
threads |
int | None |
None |
CPU cores allocation (defaults to max(1, cpu_count - 2)). |
wake_lock |
bool |
True |
Holds Android CPU WakeLock during generation to prevent screen-off suspension. |
export_gallery |
bool |
True |
Copies to ~/storage/pictures/TermuxDiffusion/ and broadcasts MediaScanner. |
timeout |
float |
1800.0 |
Max allowed execution timeout in seconds (default: 30 min). |
2. Negative Prompt Configuration APIs
set_default_negative_prompt(prompt: str | None): Globally configures or clears the default negative prompt across all generate() calls.get_default_negative_prompt() -> str | None: Inspects the active global negative prompt (returns None by default).get_quality_guard_negative_prompt() -> str: Returns the recommended quality-guard preset ("lowres, bad quality, blur, deformed, distorted, extra limbs, artifacts").
3. Model & Cache Management Functions
download_model(model_name_or_url, cache_dir=None, force=False, progress_callback=None): Streams GGUF weights with chunked resume.register_model(name, repo_id=None, filename=None, url=None, description=None): Registers a custom alias for Hugging Face or URL models.list_cached_models(cache_dir=None): Returns a list of dictionaries with cached model names, sizes, and file paths.clear_cache(cache_dir=None): Removes cached weights to reclaim storage.set_cache_dir(path) / get_cache_dir(): Configures custom storage paths (e.g. external SD cards).
3. Platform & Hardware Diagnostics
get_memory_info(): Inspects total RAM, free RAM, available RAM, and swap (Samsung RAM Plus).get_optimal_thread_count(): Calculates optimal thread affinity considering big.LITTLE core topologies.run_doctor(): Runs a 6-phase pre-flight diagnostic health check.export_to_android_gallery(image_path): Manually exports any image into Samsung Gallery and triggers MediaScanner.TermuxWakeLock(enabled=True): Context manager to hold CPU WakeLock.
4. Full CLI Command Matrix
| Command |
Arguments |
Description |
termux-diffusion generate |
"<prompt>" [-m model] [--device cpu|gpu] [--steps N] [--cfg N] [-o file.png] [-W 512] [-H 512] [-t threads] [-s seed] [--no-wakelock] [--no-gallery] |
Executes diffusion inference with custom options. |
termux-diffusion download |
<model_name> |
Pre-downloads and caches model weights. |
termux-diffusion models |
(None) |
Displays catalog of available presets and cached models. |
termux-diffusion doctor |
(None) |
Runs automated 6-phase pre-flight diagnostic health check. |
termux-diffusion install |
[--force] |
Compiles native ARM64 Bionic engine binary. |
termux-diffusion clear |
(None) |
Clears cached weights to free storage. |
