Skip to content

SD.Next API

SD.Next provides a full HTTP REST API for interacting with the server and running operations.

Docs

Interactive API documentation is served at two endpoints in different presentations:

  • /docs (Swagger UI)
  • /redocs (ReDoc)

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

The API has two groups: internal and public. All public API endpoints start with /sdapi/.

Warning

Internal API endpoints are not intended for public use and are subject to change without notice

Control Examples

SD.Next includes API examples in both Python and JavaScript. All examples are in the /cli/ folder:

  • Generate endpoints
    api-txt2img.js api-txt2img.py api-img2img.py api-control.py api-faceid.py api-pulid.js
  • Status endpoints
    api-progress.py api-history.py api-json.py
  • Utility endpoints
    api-detect.py api-grid.py api-info.py api-mask.py api-model.js api-preprocess.py api-upscale.py api-vqa.py

Authentication

If the SD.Next server starts with --auth, all API endpoints require authentication. This is strongly recommended when the server is exposed to a public network.

SD.Next uses HTTP Basic authentication, so requests must include encoded username and password credentials. See the Python and JavaScript examples for request format details.

Immediate vs Deferred Results

Most SD.Next API endpoints are synchronous and return only after the operation finishes. For example, /sdapi/v1/txt2img returns generated images in the response as base64.

For long-running tasks, you can submit the request and track progress separately: - Monitor live progress with /sdapi/v1/progress. - Get completed task results with /sdapi/v1/history/id={id}.

The history endpoint also returns files created by the operation. After you have a filename, download it with /file={filename}.

Note

For security reasons, file access and downloads are only allowed inside the SD.Next folder structure and folders marked as output folders in SD.Next settings. Request for files outside of these folders will be rejected with 403 Forbidden error
If you want to allow access to other folders, use --allowed-paths command line flag

Image

Progress Reporting

While a task runs, query /sdapi/v1/progress with a GET request to check current status. This is useful because endpoints such as txt2img block until generation completes.

Optionally set skip_current_image=true. If not set, the server includes the current step preview image in the response.

You will get back a JSON dictionary with these keys:

  • progress: a number ranging from 0 (idle / generation not started) to 1 (generation completed)
  • eta_relative: an indication of time remaining relative to the current step of the generation
  • images: A list of base64-encoded images. The list can contain multiple images for batch generation. If skip_current_image is true, this list is empty.
  • state: A JSON object with these keys:
  • job_count: Number of active jobs. 0 means idle.
  • sampling_step: Current sampling step.
  • sampling_steps: Total sampling steps for the current job.
  • skipped: true if the current generation was skipped.
  • interrupted: true if the current generation was interrupted.
  • job: Current job ID.
  • job_no: Current job number.

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 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:

{
  "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 and 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.

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

The /sdapi/v1/control endpoint supports the same operations as txt2img and img2img (with slightly different parameters), but it also supports ControlNet-specific operations. A common pattern is to generate an image with txt2img while using ControlNet units and their specific images (called override images in SD.Next parlance) to condition the generation.

To do this with the API, prepare: - Number of ControlNet units to use (minimum 1) - For each unit, the specific ControlNet model name (query /sdapi/v1/controlnets for available models) - Override image for each unit - For each unit, the preprocessor name (query /sdapi/v1/preprocessors), or None when preprocessing is not needed

Then build a POST payload for /sdapi/v1/control. Most fields are shared with /sdapi/v1/txt2img (sampler, steps, hires, and others). Control-specific fields are:

  • width_before: Output width (use instead of width)
  • height_before: Output height (use instead of height)
  • input_type: Input mode. Set to 0 for "Control only" (txt2img + ControlNet)
  • control: List of ControlNet units, where each unit contains:
  • process: ControlNet preprocessor, or None
  • model: ControlNet model name
  • strength: Conditioning strength from 0 to 1
  • start: When conditioning starts, from 0 (start) to 1 (end)
  • end: When conditioning stops, from 0 (start) to 1 (end)
  • override: Base64-encoded override image

After that, submit the entire request as POST to the server, and generation will start.