Skip to content

API_REFERENCE.md

Latest commit

 

History

History
271 lines (224 loc) · 6.94 KB

API_REFERENCE.md

File metadata and controls

271 lines (224 loc) · 6.94 KB
Raw

Stable Diffusion Server API Reference

Base Endpoints

GET /

Health check endpoint.

Response:

  • If serve_html_path configured: Returns HTML content
  • Otherwise: Plain text "Stable Diffusion Server is running"

GET /v1/models

Lists available models.

Response:

{
  "data": [
    {
      "id": "sd-cpp-local",
      "object": "model",
      "owned_by": "local"
    }
  ]
}

Image Generation

POST /v1/images/generations

Generate images from text prompts.

Request Body (JSON):

Parameter Type Required Default Description
prompt string Yes - Text description of desired image
n integer No 1 Number of images (1-8)
size string No "512x512" Image dimensions (format: {width}x{height})
output_format string No "png" Output format: "png" or "jpeg"
output_compression integer No 100 Compression quality (0-100)

Special Feature - sd_cpp_extra_args: You can embed additional parameters in the prompt using XML tags:

<sd_cpp_extra_args>{"sample_steps": 30, "cfg_scale": 8.5}</sd_cpp_extra_args>

These parameters follow the SDGenerationParams structure and are automatically extracted from the prompt.

Response (JSON):

{
  "created": 1234567890,
  "output_format": "png",
  "data": [
    {
      "b64_json": "base64_encoded_image_data"
    }
  ]
}

Error Responses:

  • 400: Missing/invalid prompt, invalid output_format, invalid sd_cpp_extra_args, invalid params
  • 500: Server error with details in error and message fields

POST /v1/images/edits

Edit or generate images using reference images and optional masks.

Request (multipart/form-data):

Field Type Required Default Description
prompt string Yes - Text description
image[] file(s) Yes - One or more reference images
mask file No - Optional mask image (1-channel)
n string No "1" Number of images (1-8)
size string No "512x512" Output dimensions
output_format string No "png" "png" or "jpeg"
output_compression string No "100" Compression quality (0-100)

Special Feature - sd_cpp_extra_args: Same as /v1/images/generations - embed extra parameters in the prompt.

Response (JSON):

{
  "created": 1234567890,
  "output_format": "png",
  "data": [
    {
      "b64_json": "base64_encoded_image_data"
    }
  ]
}

Error Responses:

  • 400: Not multipart/form-data, missing prompt/images, invalid format
  • 500: Server error

AUTOMATIC1111 / Forge Compatible Endpoints

POST /sdapi/v1/txt2img

Text-to-image generation (A1111 compatible).

Request Body (JSON):

Parameter Type Required Default Description
prompt string Yes - Positive prompt
negative_prompt string No "" Negative prompt
width integer No 512 Image width (must be positive)
height integer No 512 Image height (must be positive)
steps integer No - Sampling steps (1-150)
cfg_scale float No 7.0 CFG scale (must be positive)
seed integer No -1 Random seed (-1 for random)
batch_size integer No 1 Number of images (1-8)
clip_skip integer No -1 CLIP skip layers
sampler_name string No "" Sampler name (see /sdapi/v1/samplers)
scheduler string No "" Scheduler name (see /sdapi/v1/schedulers)

LoRA Support: LoRA tags are extracted from the prompt using format: <lora:name:weight> or <lora:name:weight:weight2>

Response (JSON):

{
  "images": ["base64_png_1", "base64_png_2"],
  "parameters": { /* echoes input parameters */ },
  "info": ""
}

Error Responses:

  • 400: Invalid dimensions, steps out of range, invalid batch_size, missing prompt
  • 500: Server error

POST /sdapi/v1/img2img

Image-to-image generation (A1111 compatible).

Request Body (JSON): All parameters from /sdapi/v1/txt2img plus:

Parameter Type Required Default Description
init_images array Yes* - Array of base64-encoded images (with/without data URI prefix)
mask string No - Base64-encoded mask image
inpainting_mask_invert integer No 0 Invert mask (0 or 1)
extra_images array No [] Additional base64-encoded reference images
denoising_strength float No -1 Denoising strength (0.0-1.0)

*At least one of init_images required for img2img mode

Mask Behavior:

  • If no mask provided, generates full white mask (entire image editable)
  • Mask is inverted if inpainting_mask_invert is non-zero

Response: Same format as /sdapi/v1/txt2img

GET /sdapi/v1/samplers

List available sampling methods.

Response (JSON):

[
  {
    "name": "default",
    "aliases": ["default"],
    "options": {}
  },
  {
    "name": "euler_a",
    "aliases": ["euler_a"],
    "options": {}
  }
  // ... more samplers
]

Supported Samplers:

  • Default
  • euler_a / k_euler_a
  • euler / k_euler
  • heun / k_heun
  • dpm2 / k_dpm_2
  • lcm
  • ddim
  • dpm++ 2m / k_dpmpp_2m

GET /sdapi/v1/schedulers

List available schedulers.

Response (JSON):

[
  {
    "name": "default",
    "label": "default"
  },
  {
    "name": "discrete",
    "label": "discrete"
  }
  // ... more schedulers
]

GET /sdapi/v1/sd-models

Get currently loaded model information.

Response (JSON):

[
  {
    "title": "model_name",
    "model_name": "model_name",
    "filename": "model.safetensors",
    "hash": "8888888888",
    "sha256": "8888888888888888888888888888888888888888888888888888888888888888",
    "config": null
  }
]

GET /sdapi/v1/options

Get server options.

Response (JSON):

{
  "samples_format": "png",
  "sd_model_checkpoint": "model_name"
}

CORS Configuration

All endpoints support CORS with the following headers:

  • Access-Control-Allow-Origin: Reflects request origin or *
  • Access-Control-Allow-Credentials: true
  • Access-Control-Allow-Methods: *
  • Access-Control-Allow-Headers: *

OPTIONS requests return status 204.

Server Configuration

Command Line Options:

Server Options:

  • -l, --listen-ip: Server IP address (default: 127.0.0.1)
  • --listen-port: Server port (default: 1234)
  • --serve-html-path: Optional HTML file to serve at root
  • -v, --verbose: Enable verbose logging
  • --color: Enable colored logging

Context and generation options are also available (see SDContextParams and SDGenerationParams).

Error Handling

All endpoints follow this error format:

{
  "error": "error_type",
  "message": "Detailed error message"
}

Common HTTP status codes:

  • 200: Success
  • 204: No content (OPTIONS)
  • 400: Bad request (validation errors)
  • 500: Internal server error