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