JSON_API_DOCUMENTATION.md

# JSON API Documentation

This document describes the JSON-structured API endpoints for the Vestiq Fashion Analysis System.

## Overview

The Vestiq API now provides structured JSON responses for fashion analysis, making it easy to integrate with other applications and process results programmatically.

## Base URL

```
http://localhost:7861
```

## Authentication

No authentication required for current version.

## Content Types

- **Request**: `multipart/form-data` (for image uploads)
- **Response**: `application/json`

## API Endpoints

### 1. Health Check

**GET** `/health`

Check the health status of the API and models.

**Response:**
```json
{
  "status": "healthy",
  "models": "loaded", 
  "device": "cpu"
}
```

### 2. Detailed JSON Analysis

**POST** `/analyze-json`

Analyze an uploaded image and return comprehensive structured JSON response.

**Request:**
- Method: `POST`
- Content-Type: `multipart/form-data`
- Body: Form data with `file` field containing the image

**Response:**
```json
{
  "structured_analysis": {
    "upper_garment": {
      "type": "Floral midi dress",
      "color": "Navy blue base with white and pink floral print",
      "material": "Lightweight cotton or cotton blend",
      "features": "Short sleeves, round neckline, fitted bodice with A-line skirt"
    },
    "lower_garment": {
      "type": "Not applicable - dress serves as complete outfit",
      "color": "N/A",
      "material": "N/A",
      "features": "N/A"
    },
    "footwear": {
      "type": "White leather sneakers",
      "color": "Clean white with minimal accent details",
      "material": "Leather upper with rubber sole",
      "features": "Lace-up closure, low-profile design"
    },
    "outfit_summary": {
      "aesthetic": "Casual chic",
      "style_notes": "Floral pattern with modern styling",
      "occasion_suitability": "Versatile for multiple occasions",
      "color_harmony": "Cool-toned palette with neutral accents",
      "overall_assessment": "This outfit demonstrates perfect balance between feminine charm and casual comfort..."
    },
    "confidence_score": 0.847,
    "detected_items": [
      {
        "category": "dress",
        "confidence": 0.892,
        "bbox": [45.2, 78.1, 234.7, 456.3]
      },
      {
        "category": "shoes",
        "confidence": 0.756,
        "bbox": [89.4, 423.8, 187.2, 478.9]
      }
    ]
  },
  "raw_analysis": "UPPER GARMENT:\nType: Floral midi dress\n...",
  "processing_time": 2.347,
  "model_info": {
    "detection_model": "yainage90/fashion-object-detection",
    "feature_model": "yainage90/fashion-image-feature-extractor",
    "device": "cpu"
  }
}
```

### 3. Object Detection Only

**POST** `/detect-objects`

Detect fashion objects in an image and return detection results.

**Request:**
- Method: `POST`
- Content-Type: `multipart/form-data`
- Body: Form data with `file` field containing the image

**Response:**
```json
{
  "detected_items": [
    {
      "category": "top",
      "confidence": 0.892,
      "bbox": [45.2, 78.1, 234.7, 298.5]
    },
    {
      "category": "bottom", 
      "confidence": 0.756,
      "bbox": [52.1, 285.3, 227.8, 423.9]
    },
    {
      "category": "shoes",
      "confidence": 0.634,
      "bbox": [89.4, 423.8, 187.2, 478.9]
    }
  ]
}
```

### 4. Feature Extraction Only

**POST** `/extract-features`

Extract fashion features from an image.

**Request:**
- Method: `POST`
- Content-Type: `multipart/form-data`
- Body: Form data with `file` field containing the image

**Response:**
```json
{
  "feature_vector": [0.123, -0.456, 0.789, ...],
  "feature_dimension": 128,
  "processing_time": 1.234,
  "model_used": "yainage90/fashion-image-feature-extractor"
}
```

### 5. Legacy Text Analysis

**POST** `/analyze-image`

Legacy endpoint returning text-based analysis.

**Response:**
```json
{
  "analysis": "Detailed text-based fashion analysis..."
}
```

**POST** `/analyze-structured`

Legacy endpoint returning structured text analysis.

**Response:**
```json
{
  "analysis": "UPPER GARMENT:\nType: ...\n\nLOWER GARMENT:\n..."
}
```

## Data Models

### GarmentDetails
```json
{
  "type": "string",        // Garment type (e.g., "Floral midi dress")
  "color": "string",       // Color description with analysis
  "material": "string",    // Material type or inference
  "features": "string"     // Detailed features description
}
```

### OutfitSummary
```json
{
  "aesthetic": "string",           // Overall aesthetic style
  "style_notes": "string",         // Pattern and design notes
  "occasion_suitability": "string", // Suitable occasions
  "color_harmony": "string",       // Color analysis
  "overall_assessment": "string"   // Comprehensive summary
}
```

### StructuredAnalysisResponse
```json
{
  "upper_garment": "GarmentDetails",
  "lower_garment": "GarmentDetails", 
  "footwear": "GarmentDetails",
  "outfit_summary": "OutfitSummary",
  "confidence_score": "float",      // 0.0 to 1.0
  "detected_items": "array"         // Array of detection results
}
```

### DetectedItem
```json
{
  "category": "string",    // Fashion category (top, bottom, shoes, etc.)
  "confidence": "float",   // Detection confidence (0.0 to 1.0)
  "bbox": "array"         // Bounding box [x1, y1, x2, y2]
}
```

## Fashion Categories

The system recognizes these fashion categories:
- `top` - Shirts, blouses, t-shirts
- `bottom` - Pants, jeans, skirts
- `dress` - Dresses of all types
- `outer` - Jackets, blazers, coats
- `shoes` - All types of footwear
- `bag` - Bags and purses
- `hat` - Hats and headwear

## Error Responses

All endpoints return error responses in this format:

```json
{
  "detail": "Error message describing what went wrong"
}
```

Common HTTP status codes:
- `400` - Bad Request (invalid input)
- `422` - Unprocessable Entity (validation error)
- `500` - Internal Server Error (processing failed)

## Usage Examples

### cURL Examples

```bash
# Health check
curl -X GET "http://localhost:7861/health"

# Analyze image with JSON response
curl -X POST "http://localhost:7861/analyze-json" \
     -F "file=@your_image.jpg"

# Detect objects only
curl -X POST "http://localhost:7861/detect-objects" \
     -F "file=@your_image.jpg"

# Extract features only
curl -X POST "http://localhost:7861/extract-features" \
     -F "file=@your_image.jpg"
```

### Python Examples

```python
import requests

# Analyze image with structured JSON
with open('fashion_image.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:7861/analyze-json',
        files={'file': f}
    )
    result = response.json()
    
    # Access structured data
    upper_garment = result['structured_analysis']['upper_garment']
    confidence = result['structured_analysis']['confidence_score']
    processing_time = result['processing_time']

# Object detection only
with open('fashion_image.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:7861/detect-objects',
        files={'file': f}
    )
    detections = response.json()['detected_items']
    
    for item in detections:
        print(f"Found {item['category']} with {item['confidence']:.3f} confidence")
```

### JavaScript Examples

```javascript
// Analyze image with fetch API
const formData = new FormData();
formData.append('file', fileInput.files[0]);

fetch('/analyze-json', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => {
    console.log('Analysis result:', data.structured_analysis);
    console.log('Processing time:', data.processing_time);
});

// Object detection
fetch('/detect-objects', {
    method: 'POST', 
    body: formData
})
.then(response => response.json())
.then(data => {
    data.detected_items.forEach(item => {
        console.log(`${item.category}: ${item.confidence}`);
    });
});
```

## Performance Notes

- **Processing Time**: Typical analysis takes 1-5 seconds depending on image size and hardware
- **Image Formats**: Supports JPEG, PNG, WebP, and other common formats
- **Image Size**: Optimal size is 224x224 to 512x512 pixels
- **Batch Processing**: Currently single image per request
- **Rate Limiting**: No rate limiting implemented in current version

## Integration Tips

1. **Error Handling**: Always check HTTP status codes and handle errors gracefully
2. **Image Preprocessing**: Resize large images before upload for better performance
3. **Confidence Thresholds**: Filter detection results by confidence score (>0.5 recommended)
4. **Caching**: Consider caching results for identical images
5. **Async Processing**: Use async/await patterns for better user experience

## DeepFashion2 Integration

When the DeepFashion2 dataset is available, additional endpoints become active:

- `/deepfashion2/status` - Check dataset availability
- `/deepfashion2/statistics` - Get dataset statistics
- `/deepfashion2/evaluate` - Run model evaluation
- `/deepfashion2/train` - Start model training

See [DEEPFASHION2_INTEGRATION.md](DEEPFASHION2_INTEGRATION.md) for details.

## Support

For issues or questions:
1. Check the server logs for detailed error messages
2. Verify image format and size requirements
3. Test with the `/health` endpoint to ensure models are loaded
4. Review this documentation for correct API usage