API Documentation

Welcome to the Outfit Recommendation API. This service generates personalized outfit combinations tailored to your wardrobe, style preferences, body type, and must-keep items using advanced AI technology. The Spring 2025 release introduces accessory-aware ensembles and a refined confidence ladder so premium looks surface more often.

Base URL

https://service.veedrobe.com

Quick Start

Get up and running in minutes with this quick example.

curl -X POST "https://service.veedrobe.com/api/v1/generate-outfits" \
  -H "Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "season": "winter",
    "context": "work",
    "body_type": "hourglass",
    "language": "en",
    "max_results": 6,
    "min_confidence": 0.70,
    "use_llm_explanations": false,
    "previous_combinations": [
      ["item-1", "item-2", "item-3"]
    ],
    "keep_items": ["watch-01"],
    "wardrobe": [
      {
        "id": "item-1",
        "type": "top",
        "color_names": ["white"],
        "pattern": "solid",
        "fabric": "cotton",
        "season": ["all"],
        "occasions": ["work", "formal"],
        "fit_keywords": ["v_neck", "waist_defined"],
        "image_url": "/uploads/item-1.jpg"
      },
      {
        "id": "item-2",
        "type": "bottom",
        "color_names": ["black"],
        "pattern": "solid",
        "fabric": "wool",
        "season": ["winter"],
        "occasions": ["work"],
        "fit_keywords": ["high_waist"],
        "image_url": "/uploads/item-2.jpg"
      },
      {
        "id": "item-3",
        "type": "shoes",
        "color_names": ["black"],
        "pattern": "solid",
        "fabric": "leather",
        "season": ["all"],
        "occasions": ["work", "formal"],
        "image_url": "/uploads/item-3.jpg"
      },
      {
        "id": "watch-01",
        "type": "accessory",
        "color_names": ["gold"],
        "pattern": "solid",
        "season": ["all"],
        "occasions": ["work", "formal"],
        "image_url": "/uploads/watch-01.jpg"
      }
    ]
  }'

Expected Response

{
  "count": 4,
  "outfits": [
    {
      "confidence": 0.93,
      "score": 0.88,
      "label": "very_compatible",
      "reason": "Balanced winter work outfit that keeps luxe accessories understated.",
      "color_harmony": "Classic monochrome base with a single warm metallic accent.",
      "style_tips": "Tuck the knit, layer the blazer, let the watch be the statement.",
      "items": [
        "...",
        { "id": "watch-01", "type": "accessory" }
      ]
    }
  ]
}

Authentication

All API requests require authentication using an API key passed in the Api-Key header.

Request Headers

Header Value Required
Api-Key Your API key Required
Content-Type application/json Required

Security Note

Never expose your API key in client-side code. Always make requests from your backend server.

Get Your API Key

To request an API key for your application, please contact us:

info@veedrobe.com
POST /api/v1/generate-outfits

Generate personalized outfit recommendations based on wardrobe items, season, context, body type, and language preference. Explanations are available in 7 languages.

Request Parameters

Parameter Type Description Required
user_id string Unique user identifier Yes
season enum spring, summer, fall, winter, all Yes
context enum work, casual, formal, date, party, sport, all No
body_type enum hourglass, pear, apple, rectangle, athletic, oval, trapezoid, inverted_triangle, petite No
language enum en (English), tr (Turkish), de (German), es (Spanish), it (Italian), zh (Chinese), az (Azerbaijani) No
max_results integer Maximum outfits to return (1-20, default: 8) No
min_confidence float Minimum confidence score (0.0-1.0, default: 0.65) No
use_llm_explanations boolean Toggle GPT-powered explanations for the top outfit (default: false) No
previous_combinations array Previously shown outfits (each entry is an array of item IDs) to avoid repeats No
keep_items array Item IDs that must appear in every outfit (e.g., signature accessories) No
wardrobe array List of wardrobe items (3-150 items) Yes

Wardrobe Item Schema

Field Type Description Required
id string Unique item identifier Yes
type enum top, bottom, dress, outer, shoes, accessory Yes
color_names array List of color names (e.g., ["black", "white"]) Yes
pattern string solid, striped, checked, floral, geometric, dotted, printed Yes
fabric string cotton, wool, linen, silk, denim, leather, etc. No
season array Suitable seasons: ["winter"], ["all"], etc. Yes
occasions array Suitable occasions: ["work"], ["casual"], ["all"] No
fit_keywords array Fit descriptors: ["v_neck", "slim_fit", "high_waist"] No
image_url string Image URL for auto-embedding generation Yes
embedding array Pre-computed item embedding (optional) No

Response Schema

{
  "count": 4,
  "outfits": [
    {
      "confidence": 0.94,
      "score": 0.90,
      "label": "very_compatible",
      "reason": "Outstanding winter work combination—every element works in perfect harmony while the watch adds a subtle focal point.",
      "color_harmony": "Classic black-and-white base with a warm gold accent for lift.",
      "style_tips": "Build this look: black bottom → white top → black shoes. Layer a tailored blazer and let the watch stay visible for polish.",
      "items": [
        {
          "id": "item-1",
          "type": "top",
          "color_names": ["white"],
          "pattern": "solid",
          "fabric": "cotton",
          "season": ["all"],
          "occasions": ["work", "formal"],
          "fit_keywords": ["v_neck", "waist_defined"],
          "image_url": "/uploads/item-1.jpg"
        },
        {
          "id": "item-2",
          "type": "bottom",
          "color_names": ["black"],
          "pattern": "solid",
          "fabric": "wool",
          "season": ["winter"],
          "occasions": ["work"],
          "fit_keywords": ["high_waist"],
          "image_url": "/uploads/item-2.jpg"
        },
        {
          "id": "item-3",
          "type": "shoes",
          "color_names": ["black"],
          "pattern": "solid",
          "fabric": "leather",
          "season": ["all"],
          "occasions": ["work", "formal"],
          "image_url": "/uploads/item-3.jpg"
        },
        {
          "id": "watch-01",
          "type": "accessory",
          "color_names": ["gold"],
          "pattern": "solid",
          "season": ["all"],
          "occasions": ["work", "formal"],
          "image_url": "/uploads/watch-01.jpg"
        }
      ]
    }
  ]
}
POST /api/v1/process/crop-and-remove

AI-powered clothing detection and background removal using YOLOv8-seg trained on DeepFashion2 dataset. NEW: Auto-detection! Just upload an image - AI automatically detects the category (top, pants, dress, outer). Applies segmentation mask, crops to exact boundaries, and outputs a centered JPEG on white background with smooth edges.

What it does

  • Auto-detects clothing category (top, pants, dress, outer) with highest confidence
  • • Optional: Specify category manually to force specific detection
  • • Applies AI segmentation mask to isolate the garment
  • • Crops to exact boundaries with 3px edge feathering
  • • Centers on 800x800 white canvas (customizable)
  • • Returns high-quality JPEG (quality=95)

Request Parameters (Form Data)

Parameter Type Description Required
file file Image file (JPG, PNG, WebP, BMP, GIF) Yes
category enum top, pants, outer, dress (auto-detected if not provided) No
confidence float Detection confidence threshold 0.0-1.0 (default: 0.85) No
max_size integer Output square canvas size in pixels (default: 800) No

Code Examples

Simple: Auto-detect category

curl -X POST "https://service.veedrobe.com/api/v1/process/crop-and-remove" \
  -F "file=@/path/to/image.jpg" \
  --output processed_image.jpg

# The detected category will be in the X-Category response header

Advanced: Specify category and options manually

curl -X POST "https://service.veedrobe.com/api/v1/process/crop-and-remove" \
  -F "file=@/path/to/image.jpg" \
  -F "category=top" \
  -F "confidence=0.85" \
  -F "max_size=800" \
  --output processed_image.jpg

Response

Returns the processed image as image/jpeg with metadata in custom headers:

Header Description
X-Category Detected category
X-Confidence Detection confidence score (0.0-1.0)
X-Total-Time-Ms Total processing time in milliseconds
X-Output-Size-KB Output file size in kilobytes
X-Canvas-Size Canvas size (800x800, etc.)
X-Bbox Bounding box coordinates [x1, y1, x2, y2]

JSON Response Alternative

For programmatic access with detailed metadata, use the JSON endpoint:

POST /api/v1/process/crop-and-remove/json

Returns JSON with base64-encoded image and full metadata.

Accessory Support

The generator now balances accessories automatically. Up to two accessory items are layered into each outfit, respecting keep_items and avoiding duplicate combinations.

What to Expect

  • Up to two accessories are selected per outfit.
  • Accessories listed in keep_items always appear.
  • Existing combinations are deduplicated even when accessories rotate.

Best Practices

  • Provide color and fabric metadata for accessories to improve harmony scoring.
  • Use previous_combinations to rotate staple jewelry.
  • Unset use_llm_explanations for faster accessory experimentation.

Tip

If you supply more than two accessories in keep_items the excess items are still honored, so adjust your wardrobe input with that limit in mind.

Confidence Ladder

Confidence values now use a steeper sigmoid so high-performing outfits can reach the very_compatible tier more readily.

Label Confidence Range Guidance
very_compatible 0.90 - 1.00 Hero looks worth favoriting and promoting.
good 0.76 - 0.90 Everyday outfits with strong styling fundamentals.
moderate 0.61 - 0.75 Good starting points—tweak items or confidence threshold.
incompatible 0.00 - 0.60 Usually filtered out unless you set low min_confidence.

Recommendation

When upgrading from earlier versions, review any automated min_confidence thresholds. You can usually raise them by ~0.05 to spotlight the newly unlocked top-tier outfits.

GET /api/v1/health

Check the API service health status.

Response

{
  "status": "healthy",
  "service": "outfit-recommendation-service",
  "version": "1.3.1"
}

Body Types

The API supports 9 body type categories for personalized fit recommendations.

Hourglass

Balanced proportions with defined waist

Pear

Bottom-heavy, narrower shoulders

Apple

Top-heavy, broader midsection

Rectangle

Balanced, straight silhouette

Athletic

Sporty, toned physique

Inverted Triangle

Broader shoulders, narrower hips

Oval

Soft, rounded curves

Trapezoid

Muscular, defined build

Petite

Smaller, delicate frame

Fit Keywords

Use fit keywords in your wardrobe items to help the AI recommend outfits that complement specific body types.

Available Fit Keywords

v_neck waist_defined high_waist straight_fit slim_fit relaxed_fit oversized_top structured_blazer crop_top low_waist straight_leg wide_leg

These keywords help the AI understand garment fit characteristics and recommend combinations optimized for each body type.

Code Examples

curl -X POST "https://service.veedrobe.com/api/v1/generate-outfits" \
  -H "Api-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "season": "winter",
    "context": "work",
    "body_type": "hourglass",
    "language": "en",
    "max_results": 8,
    "wardrobe": [
      {
        "id": "item-1",
        "type": "top",
        "color_names": ["white"],
        "pattern": "solid",
        "fabric": "cotton",
        "season": ["all"],
        "occasions": ["work"],
        "fit_keywords": ["v_neck"],
        "image_url": "/uploads/item-1.jpg"
      },
      {
        "id": "item-2",
        "type": "bottom",
        "color_names": ["black"],
        "pattern": "solid",
        "season": ["winter"],
        "occasions": ["work"],
        "image_url": "/uploads/item-2.jpg"
      }
    ]
  }'

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

200 Success

Request was successful, outfits generated.

400 Bad Request

Invalid request parameters or validation error.

403 Unauthorized

Missing or invalid API key.

413 Request Too Large

Request body exceeds 10MB limit.

422 Unprocessable Entity

Request validation failed (Pydantic error).

429 Too Many Requests

Rate limit exceeded (10,000 requests/minute).

500 Internal Server Error

Server error (details logged internally).

Rate Limits

API requests are rate-limited to ensure fair usage and service stability.

Per IP Address

10,000 / minute

Requests per minute per IP address

Max Request Size

10 MB

Maximum request body size

Rate Limit Headers

X-RateLimit-Limit Maximum requests allowed
X-RateLimit-Remaining Requests remaining in window
X-RateLimit-Reset Time when limit resets (Unix timestamp)