Skip to content

SD.Next API

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

Docs

API documentation is generated when the server starts with the --docs flag.

Use either endpoint: - /docs - /redocs

Both endpoints expose the same API information in different formats.

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.

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.