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.
/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"
}
]
}
]
}
/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_itemsalways appear. - Existing combinations are deduplicated even when accessories rotate.
Best Practices
- Provide color and fabric metadata for accessories to improve harmony scoring.
- Use
previous_combinationsto rotate staple jewelry. - Unset
use_llm_explanationsfor 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.
/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
Requests per minute per IP address
Max Request Size
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)