Startseite Erkunden Hilfe
Anmelden
fszontagh
/
stable-diffusion.cpp-rest
1
0
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki
Struktur: 55c3467c7e
Branches Tags
stable-diffusio...
/
docs
/
API.md

API.md 21 KB
Verlauf Originalformat

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 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:

{
  "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.

Response:

{
  "message": "Logout successful"
}

GET /api/auth/validate

Validate the current authentication token.

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.

Response:

{
  "token": "string",
  "message": "Token refreshed successfully"
}

GET /api/auth/me

Get information about the currently authenticated user.

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.

Response:

{
  "status": "healthy",
  "timestamp": 1234567890,
  "version": "1.0.0"
}

GET /api/status

Get detailed server and system 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.

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

Response:

{
  "config": {
    // Server configuration details
  }
}

GET /api/system

Get system information (requires authentication).

Response:

{
  "system": {
    // System information details
  }
}

POST /api/system/restart

Restart the server (requires admin authentication).

Response:

{
  "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:

{
  "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:

{
  "model": {
    // Detailed model information
  }
}

POST /api/models/{modelId}/load

Load a specific model into memory.

Response:

{
  "message": "Model loaded successfully",
  "model": "string"
}

POST /api/models/{modelId}/unload

Unload a specific model from memory.

Response:

{
  "message": "Model unloaded successfully",
  "model": "string"
}

GET /api/models/types

Get available model types.

Response:

{
  "types": [
    "checkpoint",
    "vae", 
    "lora",
    "controlnet",
    "embedding",
    "esrgan",
    "taesd"
  ]
}

GET /api/models/directories

Get configured model directories.

Response:

{
  "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:

{
  "message": "Model refresh completed",
  "models_found": 5,
  "models_updated": 2
}

POST /api/models/hash

Generate SHA256 hashes for models.

Request Body:

{
  "model_names": ["string"],  // Optional, defaults to all models
  "force_rehash": false
}

Response:

{
  "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:

{
  "model_name": "string",
  "output_path": "string",
  "quantization_type": "f16"
}

Response:

{
  "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:

{
  "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:

{
  "operation": "load|unload|hash|convert",
  "models": ["string"],
  "options": {}
}

Response:

{
  "request_id": "string",
  "operation": "string",
  "processed": 5,
  "failed": 0,
  "results": {}
}

POST /api/models/validate

Validate model files and dependencies.

Request Body:

{
  "model_names": ["string"]
}

Response:

{
  "validation_results": {
    "model_name": {
      "valid": true,
      "errors": [],
      "warnings": [],
      "missing_dependencies": []
    }
  }
}

POST /api/models/compatible

Check model compatibility.

Request Body:

{
  "model_name": "string",
  "check_dependencies": true
}

Response:

{
  "compatible": true,
  "issues": [],
  "recommendations": []
}

POST /api/models/requirements

Get model requirements.

Request Body:

{
  "model_name": "string"
}

Response:

{
  "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:

{
  "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.

Authentication Required: Yes

Request Body:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "job_id": "string"
}

Response:

{
  "status": "success",
  "message": "Job cancelled successfully",
  "job_id": "string"
}

POST /api/queue/clear

Clear all queued jobs.

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.

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:

{
  "image_data": "base64_encoded_image",
  "width": 512,
  "height": 512,
  "maintain_aspect_ratio": true
}

Response:

{
  "resized_image_data": "base64_encoded_resized_image",
  "width": 512,
  "height": 512
}

POST /api/image/crop

Crop an image.

Authentication Required: Yes

Request Body:

{
  "image_data": "base64_encoded_image",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 200
}

Response:

{
  "cropped_image_data": "base64_encoded_cropped_image",
  "width": 200,
  "height": 200
}

Utilities

GET /api/samplers

Get available sampling methods.

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.

Authentication Required: Yes

Response:

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

GET /api/parameters

Get available generation parameters and their defaults.

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.

Authentication Required: No

Request Body:

{
  "model_name": "string",
  "width": 1024,
  "height": 1024,
  "steps": 20,
  "cfg_scale": 7.0,
  "sampling_method": "euler",
  "scheduler": "karras"
}

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "recommendations": []
}

POST /api/estimate

Estimate generation time and resource usage.

Authentication Required: Yes

Request Body:

{
  "model_name": "string",
  "width": 1024,
  "height": 1024,
  "steps": 20,
  "batch_count": 1
}

Response:

{
  "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:

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

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