Stable Diffusion REST API Documentation

Comprehensive API reference for stable-diffusion.cpp-rest server

Authentication

Authentication Methods

The API supports multiple authentication methods:

  • None: No authentication required
  • JWT: JSON Web Token authentication
  • API Key: API key authentication
  • Unix: Unix user authentication
  • PAM: Pluggable Authentication Modules

Authentication Endpoints

POST /api/auth/login

Authenticate with the server and receive an access token.

POST /api/auth/login
Request Body:
{ "username": "string", "password": "string" // Optional for Unix auth without PAM }
Response:
{ "token": "string", "user": { "id": "string", "username": "string", "role": "string", "permissions": ["string"] }, "message": "string" }

POST /api/auth/logout

Log out and invalidate the current session.

POST /api/auth/logout
Response:
{ "message": "Logout successful" }

GET /api/auth/validate

Validate the current authentication token.

GET /api/auth/validate
Headers:
Authorization: Bearer <token>
Response:
{ "user": { "id": "string", "username": "string", "role": "string", "permissions": ["string"] }, "valid": true }

POST /api/auth/refresh

Refresh the current authentication token.

POST /api/auth/refresh
Response:
{ "token": "string", "message": "Token refreshed successfully" }

GET /api/auth/me

Get information about the currently authenticated user.

GET /api/auth/me
Headers:
Authorization: Bearer <token>
Response:
{ "user": { "id": "string", "username": "string", "role": "string", "permissions": ["string"] } }

System Information

GET /api/health

Check if the server is running and healthy.

GET /api/health
Response:
{ "status": "healthy", "timestamp": 1234567890, "version": "1.0.0" }

GET /api/status

Get detailed server and system status.

GET /api/status
Response:
{ "server": { "running": true, "host": "localhost", "port": 8080 }, "generation_queue": { "running": true, "queue_size": 5, "active_generations": 1 }, "models": { "loaded_count": 2, "available_count": 10 } }

GET /api/version

Get version information about the server.

GET /api/version
Response:
{ "version": "1.0.0", "type": "release", "commit": { "short": "abc1234", "full": "abc1234567890abcdef" }, "branch": "main", "clean": true, "build_time": "2024-01-01T12:00:00Z" }

GET /api/config

Get server configuration (requires authentication).

GET /api/config
Response:
{ "config": { // Server configuration details } }

GET /api/system

Get system information (requires authentication).

GET /api/system
Response:
{ "system": { // System information details } }

POST /api/system/restart

Restart the server (requires admin authentication).

POST /api/system/restart
Response:
{ "message": "Server restart initiated" }

Model Management

GET /api/models

List all available models with filtering and pagination support.

GET /api/models
Query Parameters:
Parameter Type Required Description
type string No Filter by model type (checkpoint, vae, lora, etc.)
search string No Search in model names and descriptions
sort_by string No Sort field (name, size, date, type, loaded)
sort_order string No Sort order (asc, desc)
limit integer No Pagination limit (default: 50, 0 = no limit)
page integer No Page number (default: 1)
Note: This endpoint supports advanced filtering by model type, date ranges, size categories, and loaded status.

POST /api/models/{modelId}/load

Load a specific model into memory.

POST /api/models/{modelId}/load
Response:
{ "message": "Model loaded successfully", "model": "string" }

POST /api/models/{modelId}/unload

Unload a specific model from memory.

POST /api/models/{modelId}/unload
Response:
{ "message": "Model unloaded successfully", "model": "string" }

GET /api/models/types

Get available model types.

GET /api/models/types
Response:
{ "types": [ "checkpoint", "vae", "lora", "controlnet", "embedding", "esrgan", "taesd" ] }

POST /api/models/refresh

Rescan model directories for new models.

POST /api/models/refresh
Response:
{ "message": "Model refresh completed", "models_found": 5, "models_updated": 2 }

Image Generation

POST /api/generate/text2img

Generate images from text prompts.

POST /api/generate/text2img
Authentication Required: Yes
Request Body:
{ "model_name": "string", "prompt": "string", "negative_prompt": "string", "width": 1024, "height": 1024, "steps": 20, "cfg_scale": 7.0, "sampling_method": "euler", "scheduler": "karras", "seed": "random", "batch_count": 1, "clip_skip": 1, "n_threads": 4, "offload_params_to_cpu": false, "clip_on_cpu": false, "vae_on_cpu": false, "diffusion_flash_attn": false, "diffusion_conv_direct": false, "vae_conv_direct": false, "vae_path": "string", "clip_l_path": "string", "clip_g_path": "string", "taesd_path": "string", "embedding_dir": "string", "lora_model_dir": "string" }
Response:
{ "request_id": "string", "status": "queued", "message": "Generation request queued successfully" }

POST /api/generate/img2img

Generate images from text prompts and input images.

POST /api/generate/img2img
Authentication Required: Yes

POST /api/generate/controlnet

Generate images using ControlNet.

POST /api/generate/controlnet
Authentication Required: Yes

POST /api/generate/upscale

Upscale images using ESRGAN models.

POST /api/generate/upscale
Authentication Required: Yes

POST /api/generate/inpainting

Generate images with inpainting.

POST /api/generate/inpainting
Authentication Required: Yes

Queue Management

GET /api/queue/status

Get current queue status and all jobs.

GET /api/queue/status
Authentication Required: Yes
Response:
{ "queue": { "size": 5, "active_generations": 1, "running": true, "jobs": [ { "id": "string", "status": "queued|processing|completed|failed", "prompt": "string", "queued_time": 1234567890, "start_time": 1234567890, "end_time": 1234567890, "position": 1, "progress": 0.5, "current_step": 10, "total_steps": 20, "time_elapsed": 5000, "time_remaining": 5000, "speed": 2.0 } ] } }

GET /api/queue/job/{jobId}

Get detailed information about a specific job.

GET /api/queue/job/{jobId}
Authentication Required: Yes

POST /api/queue/cancel

Cancel a specific job.

POST /api/queue/cancel
Authentication Required: Yes
Request Body:
{ "job_id": "string" }
Response:
{ "status": "success", "message": "Job cancelled successfully", "job_id": "string" }

POST /api/queue/clear

Clear all queued jobs.

POST /api/queue/clear
Authentication Required: Yes
Response:
{ "status": "success", "message": "Queue cleared successfully" }

File Management

GET /api/queue/job/{jobId}/output/{filename}

Download a specific output file from a completed job.

GET /api/queue/job/{jobId}/output/{filename}
Authentication Required: No (public for frontend access)

Response: Binary file data with appropriate Content-Type header

GET /api/v1/jobs/{jobId}/output/{filename}

Alternative endpoint for downloading job output files.

GET /api/v1/jobs/{jobId}/output/{filename}
Authentication Required: No
Query Parameters:
Parameter Type Required Description
thumb boolean No Generate thumbnail
size integer No Thumbnail size (50-500px)

Response: Image file or thumbnail

GET /api/image/download

Download an image from a URL (CORS-free handling).

GET /api/image/download
Authentication Required: No

Response: Binary image data

Utilities

GET /api/samplers

Get available sampling methods.

GET /api/samplers
Authentication Required: Yes
Response:
{ "samplers": [ "euler", "euler_a", "heun", "dpm2", "dpmpp2s_a", "dpmpp2m", "dpmpp2mv2", "ipndm", "ipndm_v", "lcm", "ddim_trailing", "tcd" ] }

GET /api/schedulers

Get available schedulers.

GET /api/schedulers
Authentication Required: Yes
Response:
{ "schedulers": [ "discrete", "karras", "exponential", "ays", "gits", "smoothstep", "sgm_uniform", "simple" ] }

GET /api/parameters

Get available generation parameters and their defaults.

GET /api/parameters
Authentication Required: Yes
Response:
{ "parameters": { "width": { "min": 64, "max": 4096, "default": 1024, "step": 8 }, "height": { "min": 64, "max": 4096, "default": 1024, "step": 8 }, "steps": { "min": 1, "max": 150, "default": 20, "step": 1 }, "cfg_scale": { "min": 1.0, "max": 30.0, "default": 7.0, "step": 0.1 }, "batch_count": { "min": 1, "max": 50, "default": 1, "step": 1 } } }

POST /api/validate

Validate generation parameters.

POST /api/validate
Authentication Required: No

POST /api/estimate

Estimate generation time and resource usage.

POST /api/estimate
Authentication Required: Yes

Error Responses

All endpoints may return error responses in the following format:

{ "error": { "message": "Error description", "code": "ERROR_CODE", "status_code": 400, "request_id": "string", "timestamp": 1234567890 } }

Common Error Codes

  • AUTH_REQUIRED - Authentication is required for this endpoint
  • INVALID_CREDENTIALS - Invalid username or password
  • INSUFFICIENT_PERMISSIONS - User lacks required permissions
  • MODEL_NOT_FOUND - Model not found
  • MODEL_NOT_LOADED - Model not loaded into memory
  • JOB_NOT_FOUND - Job not found
  • INVALID_PARAMETERS - Invalid request parameters
  • VALIDATION_ERROR - Parameter validation failed
  • INTERNAL_ERROR - Internal server error

Authentication and Authorization

Authentication Headers

For endpoints requiring authentication, include one of the following:

JWT Token:

Authorization: Bearer <jwt_token>

API Key:

X-API-Key: <api_key>

Unix User:

X-Unix-User: <username>

Permission Levels

  • Guest: No authentication required (public endpoints)
  • User: Can generate images and manage own jobs
  • Admin: Can manage models, users, and system settings

Public Endpoints

The following endpoints do not require authentication:

  • GET /api/health
  • GET /api/status
  • GET /api/version
  • GET /api/queue/job/{jobId}/output/{filename}
  • GET /api/v1/jobs/{jobId}/output/{filename}
  • GET /api/image/download
  • POST /api/validate

Rate Limiting and Usage

Concurrent Generation Limits

The server limits concurrent generations based on configuration:

  • Default: 1 concurrent generation
  • Configurable via server settings

Queue Management

  • Jobs are processed in FIFO order
  • Queue status can be monitored via /api/queue/status
  • Jobs can be cancelled before processing starts

File Storage

  • Generated images are stored in configured output directory
  • Files are organized by job ID: {output_dir}/{job_id}/{filename}
  • Output files can be downloaded via public endpoints

WebSocket Support

The API supports WebSocket connections for real-time updates:

Connection Endpoint

ws://localhost:8080/ws

Message Types

  • job_update: Real-time job progress updates
  • queue_update: Queue status changes
  • system_update: System status changes

WebSocket Message Format

{ "type": "job_update", "data": { "job_id": "string", "progress": 0.5, "current_step": 10, "total_steps": 20, "time_elapsed": 5000, "time_remaining": 5000 } }

Examples

Basic Text-to-Image Generation

# Login curl -X POST http://localhost:8080/api/auth/login \ -H "Content-Type: application/json" \ -d '{"username": "user", "password": "pass"}' # Generate image curl -X POST http://localhost:8080/api/generate/text2img \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{ "model_name": "sd_xl_base_1.0.safetensors", "prompt": "A beautiful landscape", "width": 1024, "height": 1024, "steps": 20, "cfg_scale": 7.0 }' # Check job status curl -X GET http://localhost:8080/api/queue/job/{job_id} \ -H "Authorization: Bearer <token>"' # Download result curl -X GET http://localhost:8080/api/queue/job/{job_id}/output/image_0.png \ --output generated_image.png

Model Management

# List models curl -X GET http://localhost:8080/api/models \ -H "Authorization: Bearer <token>"' # Load a model curl -X POST http://localhost:8080/api/models/model_hash/load \ -H "Authorization: Bearer <token>"' # Get model info curl -X GET http://localhost:8080/api/models/model_hash \ -H "Authorization: Bearer <token>"'

Configuration

Environment Variables

  • STABLE_DIFFUSION_PORT: Server port (default: 8080)
  • STABLE_DIFFUSION_HOST: Server host (default: 0.0.0.0)
  • STABLE_DIFFUSION_MODELS_DIR: Models directory path
  • STABLE_DIFFUSION_OUTPUT_DIR: Output directory path

Server Configuration

The server can be configured via:

  • Command line arguments
  • Configuration file
  • Environment variables

Refer to the server documentation for detailed configuration options.

Troubleshooting

Common Issues

  1. Model not loaded: Ensure the model is loaded before generation
  2. Authentication failed: Check credentials and auth method
  3. Generation timeout: Increase timeout or reduce image size
  4. Memory errors: Reduce batch size or image dimensions

Debug Mode

Enable debug logging by setting:

  • verbose=true in server configuration
  • RUST_LOG=debug environment variable

Health Checks

Monitor server health:

curl -X GET http://localhost:8080/api/health curl -X GET http://localhost:8080/api/status