# Stable Diffusion REST API Documentation

This document provides comprehensive documentation for all REST API endpoints available in the stable-diffusion.cpp-rest server.

## Table of Contents

- [Authentication](#authentication)
- [System Information](#system-information)
- [Model Management](#model-management)
- [Image Generation](#image-generation)
- [Queue Management](#queue-management)
- [File Management](#file-management)
- [Utilities](#utilities)

---

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

**Request Body:**
```json
{
  "username": "string",
  "password": "string"  // Optional for Unix auth without PAM
}
```

**Response:**
```json
{
  "token": "string",
  "user": {
    "id": "string",
    "username": "string", 
    "role": "string",
    "permissions": ["string"]
  },
  "message": "string"
}
```

#### POST /api/auth/logout
Log out and invalidate the current session.

**Response:**
```json
{
  "message": "Logout successful"
}
```

#### GET /api/auth/validate
Validate the current authentication token.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "user": {
    "id": "string",
    "username": "string",
    "role": "string", 
    "permissions": ["string"]
  },
  "valid": true
}
```

#### POST /api/auth/refresh
Refresh the current authentication token.

**Response:**
```json
{
  "token": "string",
  "message": "Token refreshed successfully"
}
```

#### GET /api/auth/me
Get information about the currently authenticated user.

**Headers:**
- `Authorization: Bearer <token>`

**Response:**
```json
{
  "user": {
    "id": "string",
    "username": "string",
    "role": "string",
    "permissions": ["string"]
  }
}
```

---

## System Information

### GET /api/health
Check if the server is running and healthy.

**Response:**
```json
{
  "status": "healthy",
  "timestamp": 1234567890,
  "version": "1.0.0"
}
```

### GET /api/status
Get detailed server and system status.

**Response:**
```json
{
  "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.

**Response:**
```json
{
  "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).

**Response:**
```json
{
  "config": {
    // Server configuration details
  }
}
```

### GET /api/system
Get system information (requires authentication).

**Response:**
```json
{
  "system": {
    // System information details
  }
}
```

#### POST /api/system/restart
Restart the server (requires admin authentication).

**Response:**
```json
{
  "message": "Server restart initiated"
}
```

---

## Model Management

### GET /api/models
List all available models with filtering and pagination support.

**Query Parameters:**
- `type` (string): Filter by model type (checkpoint, vae, lora, etc.)
- `search` (string): Search in model names and descriptions
- `sort_by` (string): Sort field (name, size, date, type, loaded)
- `sort_order` (string): Sort order (asc, desc)
- `date` (string): Date filter (recent, old, YYYY-MM-DD)
- `size` (string): Size filter (small, medium, large, or size in MB)
- `loaded` (boolean): Filter by loaded status
- `unloaded` (boolean): Filter by unloaded status
- `limit` (integer): Pagination limit (default: 50, 0 = no limit)
- `page` (integer): Page number (default: 1)

**Response:**
```json
{
  "models": [
    {
      "name": "string",
      "type": "checkpoint",
      "file_size": 1234567890,
      "file_size_mb": 1234.56,
      "sha256": "string",
      "sha256_short": "string",
      "architecture": "string",
      "recommended_vae": "string",
      "recommended_width": 1024,
      "recommended_height": 1024,
      "recommended_steps": 20,
      "recommended_sampler": "euler",
      "required_models": [
        {
          "name": "string",
          "exists": true,
          "type": "VAE",
          "file_size": 123456789,
          "path": "string",
          "sha256": "string",
          "is_required": true,
          "is_recommended": false
        }
      ],
      "missing_models": ["string"],
      "has_missing_dependencies": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total_count": 100,
    "total_pages": 2,
    "has_next": true,
    "has_prev": false
  },
  "filters_applied": {
    "type": "checkpoint",
    "search": "string",
    "date": null,
    "size": null,
    "loaded": null,
    "unloaded": null
  },
  "sorting": {
    "sort_by": "name",
    "sort_order": "asc"
  },
  "statistics": {
    "loaded_count": 2,
    "available_count": 100
  },
  "request_id": "string"
}
```

### GET /api/models/{modelId}
Get detailed information about a specific model.

**Response:**
```json
{
  "model": {
    // Detailed model information
  }
}
```

### POST /api/models/{modelId}/load
Load a specific model into memory.

**Response:**
```json
{
  "message": "Model loaded successfully",
  "model": "string"
}
```

### POST /api/models/{modelId}/unload
Unload a specific model from memory.

**Response:**
```json
{
  "message": "Model unloaded successfully",
  "model": "string"
}
```

### GET /api/models/types
Get available model types.

**Response:**
```json
{
  "types": [
    "checkpoint",
    "vae", 
    "lora",
    "controlnet",
    "embedding",
    "esrgan",
    "taesd"
  ]
}
```

### GET /api/models/directories
Get configured model directories.

**Response:**
```json
{
  "directories": {
    "checkpoints": "/path/to/checkpoints",
    "vae": "/path/to/vae",
    "lora": "/path/to/lora",
    "controlnet": "/path/to/controlnet",
    "embeddings": "/path/to/embeddings",
    "esrgan": "/path/to/esrgan",
    "taesd": "/path/to/taesd"
  }
}
```

### POST /api/models/refresh
Rescan model directories for new models.

**Response:**
```json
{
  "message": "Model refresh completed",
  "models_found": 5,
  "models_updated": 2
}
```

### POST /api/models/hash
Generate SHA256 hashes for models.

**Request Body:**
```json
{
  "model_names": ["string"],  // Optional, defaults to all models
  "force_rehash": false
}
```

**Response:**
```json
{
  "request_id": "string",
  "status": "completed",
  "models_hashed": 5,
  "model_hashes": {
    "model_name": "sha256_hash"
  },
  "hashing_time": 12345
}
```

### POST /api/models/convert
Convert a model to a different format/quantization.

**Request Body:**
```json
{
  "model_name": "string",
  "output_path": "string",
  "quantization_type": "f16"
}
```

**Response:**
```json
{
  "request_id": "string",
  "status": "completed",
  "original_size": "2.5 GB",
  "converted_size": "1.3 GB",
  "conversion_time": 12345,
  "output_path": "string"
}
```

### GET /api/models/stats
Get model statistics.

**Response:**
```json
{
  "statistics": {
    "total_models": 100,
    "loaded_models": 5,
    "models_by_type": {
      "checkpoint": 50,
      "vae": 20,
      "lora": 30
    },
    "total_size": "15.6 GB"
  }
}
```

### POST /api/models/batch
Perform batch operations on models.

**Request Body:**
```json
{
  "operation": "load|unload|hash|convert",
  "models": ["string"],
  "options": {}
}
```

**Response:**
```json
{
  "request_id": "string",
  "operation": "string",
  "processed": 5,
  "failed": 0,
  "results": {}
}
```

### POST /api/models/validate
Validate model files and dependencies.

**Request Body:**
```json
{
  "model_names": ["string"]
}
```

**Response:**
```json
{
  "validation_results": {
    "model_name": {
      "valid": true,
      "errors": [],
      "warnings": [],
      "missing_dependencies": []
    }
  }
}
```

### POST /api/models/compatible
Check model compatibility.

**Request Body:**
```json
{
  "model_name": "string",
  "check_dependencies": true
}
```

**Response:**
```json
{
  "compatible": true,
  "issues": [],
  "recommendations": []
}
```

### POST /api/models/requirements
Get model requirements.

**Request Body:**
```json
{
  "model_name": "string"
}
```

**Response:**
```json
{
  "requirements": {
    "required_models": [],
    "recommended_models": [],
    "min_memory": "8 GB",
    "supported_features": []
  }
}
```

---

## Image Generation

### POST /api/generate/text2img
Generate images from text prompts.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "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:**
```json
{
  "request_id": "string",
  "status": "queued",
  "message": "Generation request queued successfully"
}
```

### POST /api/generate/img2img
Generate images from text prompts and input images.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "model_name": "string",
  "prompt": "string",
  "negative_prompt": "string",
  "init_image_data": "base64_encoded_image",
  "init_image_width": 512,
  "init_image_height": 512,
  "strength": 0.75,
  "width": 1024,
  "height": 1024,
  "steps": 20,
  "cfg_scale": 7.0,
  "sampling_method": "euler",
  "scheduler": "karras",
  "seed": "random",
  "batch_count": 1,
  // ... other parameters same as text2img
}
```

### POST /api/generate/controlnet
Generate images using ControlNet.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "model_name": "string",
  "prompt": "string",
  "negative_prompt": "string",
  "control_image_data": "base64_encoded_image",
  "control_image_width": 512,
  "control_image_height": 512,
  "control_strength": 1.0,
  "control_net_path": "string",
  // ... other parameters same as text2img
}
```

### POST /api/generate/upscale
Upscale images using ESRGAN models.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "model_name": "string",
  "init_image_data": "base64_encoded_image",
  "init_image_width": 512,
  "init_image_height": 512,
  "init_image_channels": 3,
  "upscale_factor": 4,
  "esrgan_path": "string",
  "n_threads": 4,
  "offload_params_to_cpu": false,
  "diffusion_conv_direct": false
}
```

### POST /api/generate/inpainting
Generate images with inpainting.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "model_name": "string",
  "prompt": "string",
  "negative_prompt": "string",
  "init_image_data": "base64_encoded_image",
  "init_image_width": 512,
  "init_image_height": 512,
  "mask_image_data": "base64_encoded_mask",
  "mask_image_width": 512,
  "mask_image_height": 512,
  // ... other parameters same as text2img
}
```

---

## Queue Management

### GET /api/queue/status
Get the current queue status and all jobs.

**Authentication Required:** Yes

**Response:**
```json
{
  "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.

**Authentication Required:** Yes

**Response:**
```json
{
  "job": {
    "id": "string",
    "status": "completed",
    "prompt": "string",
    "queued_time": 1234567890,
    "start_time": 1234567890,
    "end_time": 1234567890,
    "position": 0,
    "outputs": [
      {
        "filename": "string",
        "url": "/api/queue/job/{jobId}/output/{filename}",
        "path": "/path/to/output/file"
      }
    ],
    "error_message": "string",
    "progress": 1.0
  }
}
```

### POST /api/queue/cancel
Cancel a specific job.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "job_id": "string"
}
```

**Response:**
```json
{
  "status": "success",
  "message": "Job cancelled successfully",
  "job_id": "string"
}
```

### POST /api/queue/clear
Clear all queued jobs.

**Authentication Required:** Yes

**Response:**
```json
{
  "status": "success",
  "message": "Queue cleared successfully"
}
```

---

## File Management

### GET /api/queue/job/{jobId}/output/{filename}
Download a specific output file from a completed job.

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

**Authentication Required:** No

**Query Parameters:**
- `thumb` (boolean): Generate thumbnail
- `size` (integer): Thumbnail size (50-500px)

**Response:** Image file or thumbnail

### GET /api/image/download
Download an image from a URL (CORS-free handling).

**Authentication Required:** No

**Query Parameters:**
- `url` (string): Image URL to download

**Response:** Binary image data

### POST /api/image/resize
Resize an image.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "image_data": "base64_encoded_image",
  "width": 512,
  "height": 512,
  "maintain_aspect_ratio": true
}
```

**Response:**
```json
{
  "resized_image_data": "base64_encoded_resized_image",
  "width": 512,
  "height": 512
}
```

### POST /api/image/crop
Crop an image.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "image_data": "base64_encoded_image",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 200
}
```

**Response:**
```json
{
  "cropped_image_data": "base64_encoded_cropped_image",
  "width": 200,
  "height": 200
}
```

---

## Utilities

### GET /api/samplers
Get available sampling methods.

**Authentication Required:** Yes

**Response:**
```json
{
  "samplers": [
    "euler",
    "euler_a",
    "heun",
    "dpm2",
    "dpmpp2s_a",
    "dpmpp2m",
    "dpmpp2mv2",
    "ipndm",
    "ipndm_v",
    "lcm",
    "ddim_trailing",
    "tcd"
  ]
}
```

### GET /api/schedulers
Get available schedulers.

**Authentication Required:** Yes

**Response:**
```json
{
  "schedulers": [
    "discrete",
    "karras",
    "exponential",
    "ays",
    "gits",
    "smoothstep",
    "sgm_uniform",
    "simple"
  ]
}
```

### GET /api/parameters
Get available generation parameters and their defaults.

**Authentication Required:** Yes

**Response:**
```json
{
  "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.

**Authentication Required:** No

**Request Body:**
```json
{
  "model_name": "string",
  "width": 1024,
  "height": 1024,
  "steps": 20,
  "cfg_scale": 7.0,
  "sampling_method": "euler",
  "scheduler": "karras"
}
```

**Response:**
```json
{
  "valid": true,
  "errors": [],
  "warnings": [],
  "recommendations": []
}
```

### POST /api/estimate
Estimate generation time and resource usage.

**Authentication Required:** Yes

**Request Body:**
```json
{
  "model_name": "string",
  "width": 1024,
  "height": 1024,
  "steps": 20,
  "batch_count": 1
}
```

**Response:**
```json
{
  "estimated_time": 15000,
  "estimated_memory": "2.5 GB",
  "estimated_vram": "4.0 GB",
  "confidence": 0.85
}
```

---

## Error Responses

All endpoints may return error responses in the following format:

```json
{
  "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

```json
{
  "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

```bash
# 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

```bash
# 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:
```bash
curl -X GET http://localhost:8080/api/health
curl -X GET http://localhost:8080/api/status
```

---

For more information, refer to the project README and source code documentation.