API.md

# API

Use the Space URL as the base URL. Every endpoint requires `p` to match the lowercase `pass` environment variable.

## Health

```http
GET /health?p=PASSWORD
```

Returns `{"status":true}` when the application is ready.

## Start matrix

`POST /start?p=PASSWORD` queues a matrix run and returns its reserved `Ngr.epng` path. See `send.py` for each request body.

`generation` is required in `g{N}` form, sets the checkpoint image suffix, and uses `N` as the seed. Omitting `type` defaults to `checkpoint`, which runs the existing all-checkpoint matrix. `sampler` compares every sampler in a one-row grid, `scheduler` compares every scheduler in a one-row grid, and `sampler+scheduler` compares every combination. These comparison types resolve the numeric `model_1` and `model_2` prefixes to checkpoint names and use them for the first and second passes. Scheduler comparisons accept `sampler`; an empty value uses DPM++ 2M.

Each run uses fixed prompts, seeds, dimensions, steps, CFG, upscale settings, and denoise across its cells. The sampler comparison keeps Karras fixed. The scheduler comparison keeps its selected sampler fixed.

## Generate

```http
POST /api/generate?p=PASSWORD
Content-Type: application/json

{
  "prompt": "an orange cat",
  "style_images": [
    "BASE64_ENCODED_IMAGE_1",
    "BASE64_ENCODED_IMAGE_2"
  ],
  "style_scope": "generation",
  "style_weight": 1,
  "style_end": 1,
  "second_style_images": [
    "BASE64_ENCODED_SECOND_PASS_IMAGE"
  ],
  "second_style_weight": 0.8,
  "second_style_end": 0.7,
  "regions": [
    {
      "prompt": "orange cat, sitting, left side",
      "area": "lh",
      "strength": 1
    }
  ],
  "regional_mode": "attention",
  "detailers": [
    {
      "detector": "2_face_yolov9c.pt",
      "model": "",
      "prompt": "detailed face and eyes",
      "negative": "deformed eyes",
      "sampler": "euler",
      "scheduler": "karras",
      "steps": 18,
      "cfg": 4,
      "denoise": 0.35
    }
  ],
  "negative": "text, watermark",
  "width": 1152,
  "height": 896,
  "batch_size": 1,
  "model": "52_novaAnimeXL_ilV190.safetensors",
  "loras": [{"name": "8_bikabaka.safetensors", "strength": 1, "clip": 0}],
  "sampler": "euler_ancestral",
  "scheduler": "karras",
  "steps": 16,
  "cfg": 4,
  "upscale": true,
  "upscale_method": "bislerp",
  "upscale_scale": 1.1,
  "second_model": "",
  "second_loras": [],
  "second_sampler": "euler",
  "second_scheduler": "karras",
  "second_steps": 18,
  "second_cfg": 5,
  "denoise": 0.5,
  "return_scale": 0.5
}
```

Returns an encrypted `.epng` with ComfyUI workflow and parameter metadata, scaled after generation by the decimal `return_scale` from `0.01` through `1`, with content type `application/octet-stream`. `batch_size` generates from 1 through 8 images at once and defaults to `1`. Multiple landscape images are stacked top to bottom; portrait or square images are joined left to right. Regional prompts and their mask nodes are included in the metadata. Use `1` for full resolution. `regions` accepts up to three spatial prompts on a 5 by 5 grid. Set `regional_mode` to `attention` for Attention Couple (PPM), or omit it for soft conditioning. Regional prompts establish subjects from the first sampling step. The reduced-strength global prompt starts after the first fifth to complete the environment while regions remain active. Each internal region edge feathers by half a grid cell, so overlap adjacent regions by one cell for a smooth crossfade. `area` accepts `auto`, `full`, `tl`, `tc`, `tr`, `ml`, `mc`, `mr`, `bl`, `bc`, `br`, `th`, `mh`, `bh`, `lh`, `ch`, or `rh`. It also accepts any single cell from `a1` through `e5`, or a rectangular inclusive range such as `a1:c5`. `auto` places one prompt in the center, two left and right, or three left, center, and right. Columns run left to right and rows run top to bottom. Region strength defaults to `1`. Use the global `prompt` for environment, lighting, shared style, and composition outside regions. Omitting `regions` keeps whole-image generation unchanged. Set either scheduler to `AlignYourSteps` to use `AlignYourStepsScheduler` with fixed model type `SDXL` and the corresponding steps and denoise values. Only `prompt` is required for the built-in site defaults. `style_images` enables InstantStyle for SDXL and Illustrious checkpoints and accepts one through four raw base64 images or image data URLs up to 20 MiB each. References are center-cropped and their embeddings are averaged, allowing varied subjects and palettes to contribute their shared style. `style_weight` ranges from `0` through `5`, and `style_end` controls the fraction of sampling during which style guidance remains active. `second_style_images`, `second_style_weight`, and `second_style_end` independently style the upscale second pass. `style_scope` accepts `first`, `generation`, or `all`. `first` only styles the initial pass. `generation`, the default, styles the first pass and the upscale second pass while leaving ADetailer unconditioned to prioritize facial anatomy. `all` also styles every ADetailer pass and is useful when detailed regions visibly lose the reference style. A one-pass request treats `generation` as `first`. The exported ComfyUI workflow names the external references `style-reference-1.png` through `style-reference-4.png`. LoRAs and detailers run in array order. A blank detailer `prompt` or `negative` inherits the matching main prompt. Each request creates fresh sampler seeds. When `upscale` is true, the selected upscaler is normalized to the requested `upscale_scale` resolution before the second sampler. Leave `second_model` empty to reuse the first model and LoRA chain; otherwise `second_loras` applies to the selected second model. Width and height must be multiples of 8 from 64 through 2048; steps must be from 1 through 100.

## Archive

```http
POST /api/archive?p=PASSWORD
Content-Type: image/png
```

Stores the PNG encrypted as `.epng` in the current date's image directory without requesting a GPU.