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:

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

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

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

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

{
  "analysis": "Detailed text-based fashion analysis..."
}

POST /analyze-structured

Legacy endpoint returning structured text analysis.

Response:

{
  "analysis": "UPPER GARMENT:\nType: ...\n\nLOWER GARMENT:\n..."
}

Data Models

GarmentDetails

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

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

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

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

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

# 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

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

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

Error Handling: Always check HTTP status codes and handle errors gracefully
Image Preprocessing: Resize large images before upload for better performance
Confidence Thresholds: Filter detection results by confidence score (>0.5 recommended)
Caching: Consider caching results for identical images
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 for details.

Support

For issues or questions:

Check the server logs for detailed error messages
Verify image format and size requirements
Test with the /health endpoint to ensure models are loaded
Review this documentation for correct API usage