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