21

API

CalamitousFelicitousness edited this page 2026-08-08 22:00:13 +01:00

Table of Contents

• SD.Next API
• Docs
• Internal vs Public API
• Control Examples
• Authentication
• Immediate vs Deferred Results
• Progress Reporting
• Per-Request Settings and Overrides
• Sampler names
• Model overrides
• Video Generation
• Model selection
• Video outputs
• Examples
• T2I with ControlNet

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-video.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

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.

Video Generation

Video models are served by a dedicated endpoint group:

• POST /sdapi/v1/video: generate a video, or a single still frame, using a video model
• GET /sdapi/v1/video/models: enumerate available video engines and models
• GET /sdapi/v1/video/file: download a saved video artifact

Like txt2img, the generate endpoint is synchronous: the request blocks until generation finishes and the result is returned in the response. Progress is reported on /sdapi/v1/progress, and a running generation is cancelled with /sdapi/v1/interrupt.

Model selection

The model is selected in one of two ways:

• Registry model: pass engine and model together, using a pair returned by GET /sdapi/v1/video/models. The model is loaded on demand before generation.
• Loaded checkpoint: omit both fields to drive the currently loaded checkpoint, provided it is a video-capable pipeline. This covers video models loaded from local folders that have no registry entry.

Passing only one of the two fields is rejected with 400. An unknown engine, model, or sampler name is rejected with 404, and the valid names are listed in the error detail.

The model list reports each model's input mode: t2v (text only), i2v (requires init_image), flf2v (requires init_image and last_image), vace, animate, or workflow for modular models that select the workflow from the inputs provided. On workflow models, frames: 1 produces a single still image, returned base64-encoded in frames.

Video outputs

Disk and response outputs are controlled independently:

• mp4_video, mp4_frames, mp4_sf, and mp4_thumb select which artifacts are written to disk: the video container, individual frame images, raw frames as safetensors, and a thumbnail.
• send_video, send_frames, and send_thumbnail select which artifacts are returned base64-encoded in the response.

A video larger than the base64 size cap is returned with video empty and video_path set; the file is then downloaded with GET /sdapi/v1/video/file?file={video_path}. The file endpoint only serves paths inside the video output directory; anything else is rejected with 403 Forbidden.

Switching checkpoints through override_settings is not supported on this endpoint and is rejected with 400; the model is selected per-request through engine and model, or switched beforehand with POST /sdapi/v1/checkpoint.

A minimal request:

{
  "engine": "WAN Video",
  "model": "WAN 2.2 5B T2V",
  "prompt": "a cat walking through tall grass",
  "width": 832,
  "height": 480,
  "frames": 33,
  "steps": 20,
  "mp4_fps": 16
}

The full field list is documented under Video Generation Parameters in Parameters and served as a live schema at /docs. A complete client example is available at cli/api-video.py.

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.

© SD.Next - Check out Docs site