From 7526ee87821e8cf69e3a1e4e26f5ecc7d3508cee Mon Sep 17 00:00:00 2001 From: CalamitousFelicitousness Date: Sun, 7 Jun 2026 06:57:58 +0100 Subject: [PATCH] document per-request API usage; fix sampler_name and schedulers_sigma docs API.md: add Per-Request Settings and Overrides (single-call payload, sampler solver vs sigma split, override_settings reload behavior), cross-reference Parameters and /docs, and note docs are enabled by default (SD_NODOCS disables). Parameters.md: add a per-request note pointing to the API guide, fix the DPM++ 2M Karras sampler_name example, and correct the schedulers_sigma value list to default/karras/betas/exponential/lambdas/flowmatch. --- API.md | 48 +++++++++++++++++++++++++++++++++++++++++++----- Parameters.md | 9 +++++---- 2 files changed, 48 insertions(+), 9 deletions(-) diff --git a/API.md b/API.md index a40104f..1785274 100644 --- a/API.md +++ b/API.md @@ -4,13 +4,14 @@ SD.Next provides a full HTTP REST API for interacting with the server and runnin ## Docs -API documentation is generated when the server starts with the `--docs` flag. +Interactive API documentation is served at two endpoints in different presentations: -Use either endpoint: -- `/docs` -- `/redocs` +- `/docs` (Swagger UI) +- `/redocs` (ReDoc) -Both endpoints expose the same API information in different formats. +Both are generated from the request models, so they list every endpoint together with its accepted parameters, types, and defaults, and stay in sync with the running build. They are the authoritative reference for what each request accepts. + +The docs are enabled by default. Setting the `SD_NODOCS` environment variable disables them. ## Internal vs Public API @@ -84,6 +85,43 @@ You will get back a JSON dictionary with these keys: A common usage pattern is to poll the progress endpoint while generation is running and stop when `progress` reaches `1`. You can also check that `job_count` is `0`, but note it may briefly be `0` right before a new task starts. +## Per-Request Settings and Overrides + +Most generation parameters are per-request. The `/sdapi/v1/txt2img` and `/sdapi/v1/img2img` request models are generated from the processing class, so any processing parameter can be sent directly in the payload for a single request. The complete list of accepted fields for each endpoint is described in [Parameters](Parameters) and served as a live schema at `/docs` and `/redocs`. A separate `/sdapi/v1/options` call is not required to set the sampler, step count, CFG scale, CLiP skip, or similar values. + +A single request can carry the model, the sampler, and the per-request parameters together: + +```json +{ + "prompt": "a cat", + "negative_prompt": "blurry", + "steps": 30, + "cfg_scale": 5.0, + "seed": 12345, + "width": 1024, + "height": 1024, + "sampler_name": "DPM++ 2M SDE", + "clip_skip": 2, + "override_settings": { "sd_model_checkpoint": "modelname" } +} +``` + +### Sampler names + +`sampler_name` selects the solver. The sigma schedule (Karras, Exponential, and similar) is a separate field, `schedulers_sigma`, which accepts `default`, `karras`, `betas`, `exponential`, `lambdas`, and `flowmatch`. The exact list of solver names is returned by `/sdapi/v1/samplers`. + +A name is matched case-insensitively; an unrecognized name is rejected with `404 Sampler not found`, while the value `Default` keeps the scheduler the loaded model ships with. `Default` is also the value used when `sampler_name` is omitted. + +Automatic1111 fuses the solver and the sigma schedule into a single name, so its names do not transfer directly. For example, `DPM++ 2M Karras` is expressed here as `sampler_name: "DPM++ 2M"` together with `schedulers_sigma: "karras"`. + +The full scheduler list and the effect of each sampler option are covered in [Schedulers](Schedulers) and [Parameters](Parameters). + +### Model overrides + +The loaded model can be set per-request through `override_settings`, for example `{"sd_model_checkpoint": "modelname"}`. The output-path options listed in `restricted_opts` cannot be overridden this way. The full set of overridable settings is listed under Override Parameters in [Parameters](Parameters). + +By default `override_settings_restore_afterwards` is `true`, so an overridden option is restored once the request completes. For a checkpoint override this means the model is loaded before the request and the previous model is reloaded afterwards, which adds two model loads per request whenever the requested model differs from the one already loaded. An override that matches the current value is dropped and triggers no reload. For a workflow that issues many requests against the same model, setting the model once through `/sdapi/v1/options` or sending `override_settings_restore_afterwards: false` avoids the repeated reloads. + ## Examples ### T2I with ControlNet diff --git a/Parameters.md b/Parameters.md index 2b3ca2a..38d7922 100644 --- a/Parameters.md +++ b/Parameters.md @@ -3,8 +3,9 @@ This guide documents generation parameters available in SD.Next. It does not cover mostly static system settings. -Parameters listed here can be used in the `extra` field of styles. -Parameters from "Settings" sections (such as advanced sampler or postprocessing options) can be used in the `override_settings` dictionary for per-generation changes. +These parameters are per-request: each can be sent directly in a single `/sdapi/v1/txt2img` or `/sdapi/v1/img2img` call, placed in the `extra` field of a style, or, when backed by a setting, passed in the `override_settings` dictionary for one generation. A separate `/sdapi/v1/options` call is not needed to use them. + +The [API](API) guide is the place to look for how to build a request: payload shape, model and sampler selection, and overrides. The live, always-current request schema is served at `/docs` and `/redocs`. ## Table of Contents @@ -81,7 +82,7 @@ Controls the Variational Autoencoder (VAE) used for encoding and decoding images | Parameter | Type | Default | Details / Syntax | Description | UI Label | | :---------------------------- | :------ | :--------------- | :------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------ | -| `sampler_name` | `str` | `None` | `Values: "Euler", "Euler a", "DPM++ 2M", etc.`
`Syntax: sampler_name: DPM++ 2M Karras` | Algorithm used for image generation. Different samplers can produce different styles and qualities. | Sampling method | +| `sampler_name` | `str` | `None` | `Values: "Euler", "Euler a", "DPM++ 2M", etc.`
`Syntax: sampler_name: DPM++ 2M` | Solver used for generation. The sigma schedule (Karras, Exponential, and similar) is a separate field, `schedulers_sigma`, and is not part of this name. | Sampling method | | `steps` | `int` | `20` | `Range: 1 to 150 (typical)`
`Syntax: steps: 30` | Number of denoising steps. More steps generally mean better quality but slower generation. 20-50 is typical, with diminishing returns above 50. Settings may vary depending on sampler chosen. | Steps | | `eta` | `float` | `None` | `Range: 0.0 to 1.0`
`Syntax: eta: 0.67` | Noise multiplier for samplers that support it (like DDIM). Adds randomness to deterministic samplers. 0 = fully deterministic, 1 = maximum noise. | noise multiplier (eta) | | `eta_noise_seed_delta` | `int` | `0` | `Syntax: eta_noise_seed_delta: 31337` | An additional seed that influences the noise (eta) in ancestral samplers, allowing for variations without changing the main seed. Essentially adds 31337 to your seed. Only useful when used with originally leaked NovelAI models to replicate images. | noise seed delta (eta) | @@ -89,7 +90,7 @@ Controls the Variational Autoencoder (VAE) used for encoding and decoding images | `schedulers_solver_order` | `int` | `0` | `Range: 0 to 5` | The order of the solver for certain schedulers (e.g., DPM). Higher orders can be more accurate but slower. | sampler order | | `schedulers_use_loworder` | `bool` | `True` | `Values: True, False` | For some schedulers, uses a simpler, faster solver for the final steps of generation, also generally stabilising the output. | use simplified solvers in final steps | | `schedulers_prediction_type` | `str` | `"default"` | `Values: 'default', 'epsilon', 'sample', 'v_prediction'` | Overrides the model's configured prediction type (what the model is trained to predict at each step). Frequently used with velocity prediction (V-Pred) models. | prediction method | -| `schedulers_sigma` | `str` | `"default"` | `Values: 'default', 'karras', 'exponential', 'polyexponential'` | The algorithm used to calculate the noise schedule (sigmas). 'karras' is a popular choice. | sigma method | +| `schedulers_sigma` | `str` | `"default"` | `Values: 'default', 'karras', 'betas', 'exponential', 'lambdas', 'flowmatch'` | The algorithm used to calculate the noise schedule (sigmas). 'karras' is a popular choice. | sigma method | | `schedulers_beta_schedule` | `str` | `"default"` | `Values: 'default', 'linear', 'scaled_linear', ...` | Defines how the noise level changes over time (the beta schedule). | beta schedule | | `schedulers_use_thresholding` | `bool` | `False` | `Values: True, False` | Enables dynamic thresholding to prevent oversaturation and artifacts, especially at high CFG scales. | use dynamic thresholding | | `schedulers_timestep_spacing` | `str` | `"default"` | `Values: 'default', 'linspace', 'leading', 'trailing'` | How the timesteps are distributed across the generation process. | timestep spacing |