ai-stylegallery/prp/api-specification.md

API Specification

Overview

RESTful API built with Laravel Sanctum for authentication. Provides endpoints for image management, style application, and AI processing integration.

Base URL

/api

Authentication

Laravel Sanctum token-based authentication using Authorization: Bearer <token> header.

Response Format

All responses use JSON format with consistent structure:

Success Response

{
  "message": "Operation completed successfully",
  "data": { ... }
}

Error Response

{
  "error": "Error description",
  "message": "Detailed error message"
}

Endpoints

1. Image Management

1.1 Get Images

Endpoint: GET /api/images

Authentication: Not required (filtered by visibility rules)

Description: Retrieves paginated list of images with automatic filesystem synchronization

Query Parameters:

• None

Response:

[
  {
    "image_id": 1,
    "path": "/storage/uploads/image.jpg",
    "name": "image.jpg",
    "is_temp": false,
    "is_public": true,
    "is_new": true
  }
]

Business Logic:

• Synchronizes filesystem with database before returning results
• Filters images based on authentication status
• Adds is_new flag for recently uploaded images (within configurable timespan)
• Returns images in descending order by updated_at

Error Codes:

• 500: Internal server error during synchronization

---

1.2 Upload Image

Endpoint: POST /api/images/upload

Authentication: Not required

Description: Uploads new image file to the gallery

Request Body (multipart/form-data):

{
  "image": "file (JPEG, PNG, WebP, max 10MB)"
}

Response:

{
  "message": "Image uploaded successfully",
  "image_id": 1,
  "path": "/storage/uploads/new-image.jpg"
}

Validation Rules:

• image: required, image file, mime types: jpeg,png,webp, max:10240KB

Business Logic:

• Generates unique filename to prevent conflicts
• Stores in public/storage/uploads/ directory
• Creates database record with is_public = true
• Returns full URL path for immediate use

Error Codes:

• 422: Validation failed (invalid file type/size)
• 500: File storage error

---

1.3 Apply Style to Image

Endpoint: POST /api/images/style-change

Authentication: Not required (same-origin check)

Description: Initiates AI style transformation process

Headers:

Referer: https://yourdomain.com (same-origin validation)

Request Body:

{
  "image_id": 1,
  "style_id": 1
}

Response:

{
  "message": "Style change request sent",
  "prompt_id": "comfyui-job-123",
  "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "plugin": "comfyui"
}

Validation Rules:

• image_id: required, exists in images table
• style_id: nullable, exists in styles table

Business Logic:

• Validates same-origin request for security
• Loads appropriate AI plugin based on style's API provider
• Updates image record with comfyui_prompt_id and style_id
• Returns tracking information for frontend progress monitoring

Error Codes:

• 403: Unauthorized origin
• 404: Image or style not found
• 422: Validation failed
• 500: Plugin processing error

---

1.4 Fetch Styled Image Result

Endpoint: GET /api/images/fetch-styled/{promptId}

Authentication: Not required

Description: Retrieves result of completed AI style transformation

Path Parameters:

• promptId: string (ComfyUI job identifier)

Response:

{
  "message": "Styled image fetched successfully",
  "styled_image": {
    "id": 2,
    "path": "/storage/uploads/styled_image.png",
    "is_temp": true
  }
}

Business Logic:

• Finds image record by comfyui_prompt_id
• Loads appropriate AI plugin to fetch result
• Saves styled image to filesystem
• Creates new database record for styled image
• Links styled image to original via original_image_id

Error Codes:

• 404: Image not found or still processing
• 500: Plugin fetch error or file save error

---

1.5 Keep Styled Image

Endpoint: POST /api/images/keep

Authentication: Required (Sanctum)

Description: Converts temporary styled image to permanent

Request Body:

{
  "image_id": 2
}

Response:

{
  "message": "Image kept successfully"
}

Validation Rules:

• image_id: required, exists in images table

Business Logic:

• Verifies user owns the image
• Sets is_temp = false on image record
• Image becomes permanent part of user's gallery

Error Codes:

• 401: Unauthenticated
• 404: Image not found
• 403: User doesn't own image

---

1.6 Delete Image

Endpoint: DELETE /api/images/{image}

Authentication: Required (Sanctum)

Description: Permanently removes image and file

Path Parameters:

• image: integer (image ID)

Response:

{
  "message": "Image deleted successfully"
}

Business Logic:

• Verifies user owns the image
• Deletes physical file from storage
• Removes database record
• Cascading: styled images deleted when original is deleted

Error Codes:

• 401: Unauthenticated
• 404: Image not found
• 403: User doesn't own image
• 500: File deletion error

---

1.7 Get Image Status (Deprecated)

Endpoint: GET /api/images/status

Authentication: Not required

Description: Legacy endpoint for image processing status

Query Parameters:

{
  "image_id": 1,
  "api_provider_name": "ComfyUI"
}

Response:

{
  "status": "unknown"
}

Note: Currently returns static response, replaced by WebSocket progress

---

2. Style Management

2.1 Get Available Styles

Endpoint: GET /api/styles

Authentication: Not required

Description: Retrieves all enabled styles for style selector

Response:

[
  {
    "id": 1,
    "title": "Oil Painting",
    "description": "Classic oil painting style",
    "preview_image": "/storage/style_previews/oil-painting.jpg",
    "enabled": true
  }
]

Business Logic:

• Returns only enabled styles
• Includes preview images for UI display
• Ordered by sort_order field

Error Codes:

• 500: Database query error

---

3. AI Provider Management

3.1 Get ComfyUI URL

Endpoint: GET /api/comfyui-url

Authentication: Not required

Description: Returns WebSocket URL for real-time progress updates

Query Parameters (optional):

{
  "style_id": 1,
  "image_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
  "comfyui_url": "https://your-comfyui-server.com"
}

Business Logic:

• Determines appropriate API provider based on style or image
• Falls back to first available ComfyUI provider if none specified
• Returns base URL for WebSocket connection

Error Codes:

• 404: No enabled ComfyUI provider found

---

4. User Management

4.1 Get Authenticated User

Endpoint: GET /api/user

Authentication: Required (Sanctum)

Description: Returns current authenticated user information

Response:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user",
  "theme_preference": "light",
  "locale": "en"
}

Error Codes:

• 401: Unauthenticated

---

5. Admin Management

5.1 Store Navigation State

Endpoint: POST /api/admin/navigation-state

Authentication: Required (Sanctum)

Description: Saves admin panel navigation preferences

Request Body:

{
  "state": "collapsed",
  "active_tab": "dashboard"
}

Response:

{
  "message": "Navigation state saved"
}

Business Logic:

• Stores UI state preferences for admin users
• Used by Filament admin panel for user experience

---

WebSocket Integration

ComfyUI Progress Updates

Connection:

WebSocket URL: ws://{comfyui-server-host}/ws

Message Format:

{
  "type": "progress",
  "data": {
    "prompt_id": "job-123",
    "value": 50,
    "max": 100
  }
}

Frontend Handling:

• Connect to WebSocket after receiving prompt_id from style-change endpoint
• Monitor progress messages for matching prompt_id
• Update UI progress bar based on value/max percentage
• Fetch final result when progress reaches 100%

Error Handling

HTTP Status Codes

• 200: Success
• 201: Created
• 400: Bad Request
• 401: Unauthenticated
• 403: Forbidden
• 404: Not Found
• 422: Validation Error
• 500: Internal Server Error

Error Response Structure

{
  "error": "Human readable error message",
  "message": "Technical details for debugging",
  "errors": {
    "field_name": ["Specific field validation errors"]
  }
}

Rate Limiting

Current Implementation

• No explicit rate limiting configured
• External AI services may have their own limits
• Consider implementing for production deployment

Recommended Limits

• Image upload: 10 per minute per user
• Style change requests: 5 per minute per user
• API calls: 1000 per hour per user

Security Considerations

Authentication

• Laravel Sanctum for API authentication
• Bearer token in Authorization header
• CSRF protection for web routes

Input Validation

• All inputs validated using Laravel Form Requests
• File upload restrictions (type, size)
• SQL injection prevention via Eloquent ORM

Same-Origin Policy

• Style change endpoint validates request origin
• Prevents CSRF attacks from external sites

File Security

• Uploaded files stored outside web root
• File type validation prevents malicious uploads
• Secure file permissions on storage directories

Performance Considerations

Caching

• No explicit caching implemented
• Consider caching for frequently accessed data:
  • Available styles list
  • User permissions
  • API provider configurations

Database Optimization

• Eager loading for relationships (styles → ai_models → api_providers)
• Consider indexes on frequently queried fields
• Automatic filesystem synchronization on image listing

File Storage

• Images stored on local filesystem
• Consider CDN integration for global distribution
• Automatic cleanup of temporary files

Future API Enhancements

Potential Endpoints

• GET /api/images/{id}/history - Processing history for image
• POST /api/images/batch-style-change - Apply style to multiple images
• GET /api/styles/search?q=term - Search styles by name/description
• POST /api/users/preferences - Update user preferences
• GET /api/admin/stats - Application statistics for admins

WebSocket Enhancements

• Real-time notifications for all users
• Live gallery updates when new images are processed
• Admin monitoring of processing queue status