Skip to content

SD.Next API

SD.Next has a rich HTTPRest API interface that allows to interact with the server and perform any operations

Docs

API documentation is dynamically generated if server is started with --docs command line flag
and can be accessed at /docs or /redocs endpoints

Both endpoints provide the same information, but in different formats - use one that you prefer

Internal vs Public API

The API is divided into two parts - 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

Examples

SD.Next includes several examples of how to use the API via Python or JavaScript
All examples are located in /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-interrogate.py api-mask.py api-model.js api-preprocess.py api-upscale.py api-vqa.py

Authentication

If SD.Next server is started with --auth command line flag, then all API endpoints require authentication
This is highly recommended if your server is exposed over a public network
API endpoints use HTTP Basic authentication, which means you need to provide encoded username and password in the request
See examples for both Python and JavaScript on how to do this

Immediate vs Deferred Results

Most of SD.Next API endpoints are synchronous and only return when the operation is completed with actual result of the operation in the response object
For example, using /sdapi/v1/txt2img endpoint will return the generated image in the response object encoded with base64

However, if you want to perform long running operations, you can trigger them using standard endpoints, but not wait for the result
Instead either monitor server for real-time progress or for historical results
- monitor the live progress of the operation using /sdapi/v1/progress endpoint
- get the result of any operation using /sdapi/v1/history/id={id} endpoint
note: history endpoint will also return the list of files that may have been created as a result of the operation
And once you have the filename, you can download it using /file={filename} endpoint

Note

For security reason access and download of files is only allowed within sdnext folder structure and any folders marked as output folders within sdnext 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 you have a task running, you can query the /sdapi/v1/progress endpoint using a GET request to see what the server is doing (since endpoints like txt2img block the call until the generation is completed). Optionally you can specify the paramerer skip_current_image=true: if not set, the server will send the preview image for the step of the generation it is at.

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, one or more depending how many you generate in a single batch (if skip_current_image is true, this list is empty)
  • state: A JSON dictionary with the following keys.
    • job_count: The number of jobs running, if 0, the server is idle; if > 1, the server is running one or more job
    • sampling_step: The current sampling step of the current job
    • sampling_steps: The number of sampling steps in the current job
    • skipped: A boolean value, true if the current generation was skipped
    • interrupted: A boolean value, true if the current generation was interrupted
    • job: A string with the current job ID
    • job_no: The current job number

A typical use of this API would be to poll the progress endpoint while a generation is running, collecting information, and stopping while progress is 1. You may want also to check that job_count is 0, but you must be aware that it might be 0 right before a task starts.

Examples

T2I with ControlNet

The /sdapi/v1/control endpoint supports doing the same operations as txt2img and img2img (with slightly different parameters), but in addition to that it supports specific operations like using ControlNet. ControlNet can be used in many different ways, but a very common usage is to generate an image with txt2img and have the ControlNet units and their specific images (called override images in SD.Next parlance) condition the generation.

To do so with the API, you will first need: - The number of ControlNet units to use (minimum 1) - For each unit, the naeme of the specific ControlNet model to use (you can obtain a list by querying the /sdapi/v1/controlnets endpoint) - The override image to use for each unit - For each unit, the name of the specific preprocessor to apply to the image (a list can be obtained by querying the /sdapi/v1/preprocessors endpoint), or None if no preprocessing is required

Then you need to prepare your payload to be sent via POST to the /sdapi/v1/control endpoint. You can refer to the documentation of the /sdapi/v1/txt2img endpoint for most of the parameters like sampler, steps, hires, and so on. Here are the ones that are specific of this one:

- `width_before`: The width of the generated image (use instead of `width`)
- `height_before`: The height of the generated image (use instead of `height`)
- `input_type`: The type of input you are supplying, set it to 0, which corresponds to "Control only" (aka txt2img + ControlNet)
- `control`: This is a list of your ControlNet units, each one as follows:
    - `process`: The ControlNet preprocessor to use, or `None`
    - `model`: The name of the ControlNet model to use
    - `strength`: The strength of the conditioning, ranging from 0 to 1
    - `start`: A value ranging from 0 (generation start) to 1 (generation end), indicating when conditioning will be applied
    - `end`: A value from ranging from 0 (generation start) to 1 (generation end), indicating when conditioning will be stopped
    - `override`: A base64-encoded string of the image to be used as override image

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