API Documentation

Welcome to the Outfit Recommendation API. This service generates personalized outfit combinations tailored to your wardrobe, style preferences, and body type using advanced AI technology.

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": 8,
    "min_confidence": 0.65,
    "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"
      }
    ]
  }'

Expected Response

{
  "count": 3,
  "outfits": [
    {
      "confidence": 0.85,
      "score": 0.82,
      "label": "very_compatible",
      "reason": "Well-balanced winter work outfit with excellent fit",
      "items": [...]
    }
  ]
}

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
`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": 3,
  "outfits": [
    {
      "confidence": 0.92,
      "score": 0.89,
      "label": "very_compatible",
      "reason": "Outstanding winter work combination—every element works in perfect harmony. Top (white, solid) + Bottom (black, solid) + Footwear (black, solid). Monochromatic black approach creates an elegant silhouette—elongating effect and flattering lines.",
      "color_harmony": "Classic black and white contrast creates striking visual impact.",
      "style_tips": "Build this look: black bottom → white top → black shoes. Winter layering perfection—outerwear provides cold-weather comfort. Professional polish achieved—keep jewelry understated and let the outfit speak. A stellar combination—definitely add to your favorites!",
      "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"
        }
      ]
    }
  ]
}

GET /api/v1/health

Check the API service health status.

Response

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

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"
      }
    ]
  }'

import requests

API_URL = "https://service.veedrobe.com/api/v1/generate-outfits"
API_KEY = "your-api-key-here"

payload = {
    "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"
        }
        # Add more items...
    ]
}

headers = {
    "Api-Key": API_KEY,
    "Content-Type": "application/json"
}

response = requests.post(API_URL, json=payload, headers=headers)
outfits = response.json()

print(f"Generated {outfits['count']} outfits")
for outfit in outfits['outfits']:
    print(f"Confidence: {outfit['confidence']:.2f} - {outfit['reason']}")

const API_URL = 'https://service.veedrobe.com/api/v1/generate-outfits';
const API_KEY = 'your-api-key-here';

const payload = {
  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'
    }
    // Add more items...
  ]
};

fetch(API_URL, {
  method: 'POST',
  headers: {
    'Api-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(`Generated ${data.count} outfits`);
    data.outfits.forEach(outfit => {
      console.log(`Confidence: ${outfit.confidence} - ${outfit.reason}`);
    });
  })
  .catch(error => console.error('Error:', error));

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)