StyleGPT

API v4 Documentation

Complete reference for StyleGPT's latest API endpoints

API Status: Operational
Last Updated: Today

StyleGPT API v4 Documentation

The StyleGPT v4 API provides advanced AI-powered fashion intelligence capabilities including conversational styling, semantic search, vector similarity matching, and AI-generated outfit visualization.

Table of Contents

Authentication

All v4 API endpoints require authentication via Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Demo Access

For testing purposes, you can use the demo token:

Authorization: Bearer DEMO

Note: Demo access has reduced rate limits and may have feature restrictions.

Rate Limiting

Endpoint Authenticated Users Demo Users
Chat API 30 requests/minute 15 requests/minute
Dataset Search 100 requests/minute 50 requests/minute
Image Generation 50 requests/minute 25 requests/minute

Rate limit headers are included in all authenticated responses:

  • X-RateLimit-Resource: The specific API resource being accessed (e.g., "api.v4.chat")
  • X-RateLimit-Quota-Limit: Monthly quota limit (number or "unlimited")
  • X-RateLimit-Quota-Remaining: Requests remaining in current monthly quota (number or "unlimited")
  • X-RateLimit-Quota-Reset: Unix timestamp when monthly quota resets (beginning of next month)
  • X-RateLimit-RPM-Limit: Requests per minute limit
  • X-RateLimit-RPM-Remaining: Requests remaining in current minute window
  • X-RateLimit-RPM-Reset: Unix timestamp when RPM limit resets (60 seconds from now)
  • Retry-After: Seconds to wait before retrying (only present when rate limited)

Error Handling

The API uses standard HTTP status codes and returns consistent error response format:

{
  "error": "Descriptive error message for developers"
}

Endpoints

Chat API

Endpoint: POST /api/v4/chat

Advanced AI styling assistant with conversational interface and web search capabilities.

Request Body

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text", 
          "text": "Create a business casual outfit"
        }
      ]
    }
  ],
  "useAdvancedStyling": true,
  "brand": "hugo boss",
  "chatId": "optional-chat-session-id"
}

Parameters

Field Type Required Description
messages Array Yes Array of conversation messages
messages[].role String Yes Message role: user, assistant, system
messages[].content Array Yes Message content parts
messages[].content[].type String Yes Content type: text, image_url
messages[].content[].text String Required for text Text content
useAdvancedStyling Boolean No Enable web search for latest trends (default: false)
brand String No Filter results by specific brand
chatId String No Session ID for conversation continuity

Response

{
  "responseMessage": "Here's a perfect business casual outfit with a modern twist...",
  "functionCall": {
    "name": "generateOutfit",
    "parameters": {
      "descriptions": [
        "Men's slim-fit navy cotton chinos",
        "Men's light blue cotton dress shirt",
        "Men's navy wool blazer"
      ]
    }
  },
  "personaDescription": "Professional business casual style",
  "followUps": [
    "Make it more formal",
    "Try different colors", 
    "Add accessories",
    "Show summer alternatives"
  ]
}

Example Usage

// Basic styling request
const response = await fetch('/api/v4/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [{
      role: 'user',
      content: [{
        type: 'text',
        text: 'I need a formal outfit for a wedding reception'
      }]
    }],
    useAdvancedStyling: true
  })
});

const styling = await response.json();
console.log(styling.responseMessage);

// Multi-turn conversation
const response = await fetch('/api/v4/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    messages: [
      {
        role: 'user',
        content: [{ type: 'text', text: 'Create a casual summer outfit' }]
      },
      {
        role: 'assistant', 
        content: [{ type: 'text', text: 'Here\'s a great summer look...' }]
      },
      {
        role: 'user',
        content: [{ type: 'text', text: 'Make it more colorful' }]
      }
    ],
    chatId: 'session-123',
    brand: 'zara'
  })
});

Dataset Text Search

Endpoint: POST /api/v4/dataset/search/text

Semantic search across fashion dataset using natural language queries.

Request Body

{
  "query": "navy blue cotton dress shirt with modern fit",
  "limit": 10,
  "filters": {
    "metadata.gender": "mens",
    "metadata.article_type": "shirt",
    "origin.brand": "hugo boss"
  }
}

Parameters

Field Type Required Description
query String Yes Natural language search query (max 512 characters)
limit Number No Number of results to return (1-100, default: 5)
filters Object No MongoDB-style filters for metadata and origin fields

Common Filter Fields

Filter Path Description Example Values
metadata.gender Target gender "mens", "womens"
metadata.article_type Clothing category "shirt", "pants", "dress", "jacket"
metadata.primary_colors Primary colors "navy blue", "black", "white"
origin.brand Brand name "hugo boss", "zara", "nike"
origin.url Retailer domain "hugoboss.com", "zara.com"

Response

{
  "results": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "metadata": {
        "article_type": "shirt",
        "gender": "mens", 
        "description": "Navy cotton dress shirt with spread collar",
        "primary_colors": ["navy blue", "white"],
        "formality": "business_casual",
        "patterns": ["solid"]
      },
      "origin": {
        "brand": "Hugo Boss",
        "url": "hugoboss.com",
        "product_url": "https://hugoboss.com/...",
        "image_urls": ["https://images.hugoboss.com/..."]
      },
      "score": 0.8947,
      "embeddings": {}
    }
  ]
}

Example Usage

// Basic text search
const response = await fetch('/api/v4/dataset/search/text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'comfortable athletic sneakers for running',
    limit: 5
  })
});

const { error, results } = await response.json();

if (error) {
  alert(error);
  return;
}

results.forEach(item => {
  console.log(`${item.metadata.article_type}: ${item.metadata.description}`);
  console.log(`Score: ${item.score.toFixed(3)}`);
});

// Advanced filtered search
const response = await fetch('/api/v4/dataset/search/text', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'elegant evening dress',
    limit: 20,
    filters: {
      'metadata.gender': 'womens',
      'metadata.formality': { '$in': ['formal', 'semi_formal'] },
      'metadata.primary_colors': { '$in': ['black', 'navy blue'] },
      'origin.brand': { '$in': ['hugo boss', 'zara'] }
    }
  })
});

Endpoint: POST /api/v4/dataset/search/embedding

Vector similarity search using pre-computed embeddings for advanced ML applications.

Request Body

{
  "embedding": [0.1, -0.2, 0.3, ...],
  "limit": 5,
  "filters": {
    "metadata.gender": "womens",
    "origin.brand": "zara"
  }
}

Parameters

Field Type Required Description
embedding Array Yes 512-dimensional float array
limit Number No Number of results to return (1-100, default: 5)
filters Object No MongoDB-style filters (same as text search)

Response

Same format as text search, with vector similarity scores.

Example Usage

// Vector similarity search
const response = await fetch('/api/v4/dataset/search/embedding', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    embedding: embeddings.textEmbedding, // From CLIP API
    limit: 10,
    filters: {
      'metadata.article_type': 'dress',
      'metadata.gender': 'womens'
    }
  })
});

const similarItems = await response.json();

Outfit Image Generation

Endpoint: POST /api/v4/outfit/image/generate

Generate photorealistic images of models wearing specified clothing items.

Request Body

{
  "imageUrls": [
    "https://example.com/white-shirt.jpg",
    "https://example.com/navy-blazer.jpg",
    "https://example.com/dark-jeans.jpg"
  ],
  "modelDescription": "Professional 28-year-old model, athletic build, confident pose"
}

Parameters

Field Type Required Description
imageUrls Array Yes URLs of clothing item images (1-10 items)
modelDescription String Yes Description of desired model appearance (max 500 characters)

Model Description Guidelines

  • Age range: "20s", "30s", "middle-aged"
  • Build: "athletic", "slim", "curvy", "average"
  • Pose: "confident", "casual", "professional", "relaxed"
  • Style: "professional", "casual", "editorial", "lifestyle"

Response

{
  "imageData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA..."
}

Example Usage

// Generate outfit visualization
const response = await fetch('/api/v4/outfit/image/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    imageUrls: [
      'https://cdn.shopify.com/white-blouse.jpg',
      'https://cdn.shopify.com/black-skirt.jpg',
      'https://cdn.shopify.com/heels.jpg'
    ],
    modelDescription: 'Confident professional woman in her 30s, business setting'
  })
});

const { imageData } = await response.json();

// Display generated image
const img = document.createElement('img');
img.src = imageData;
document.body.appendChild(img);

// Batch generation for multiple outfits
const outfits = [
  {
    items: ['shirt1.jpg', 'pants1.jpg'],
    model: 'Casual young man, relaxed pose'
  },
  {
    items: ['dress1.jpg', 'jacket1.jpg'], 
    model: 'Professional woman, confident stance'
  }
];

const results = await Promise.all(
  outfits.map(outfit => 
    fetch('/api/v4/outfit/image/generate', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        imageUrls: outfit.items,
        modelDescription: outfit.model
      })
    }).then(res => res.json())
  )
);

Status Codes

Code Meaning Description
200 OK Request successful
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient subscription permissions
422 Unprocessable Entity Invalid request parameters
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error occurred

Common Error Responses

Authentication Errors

// 401 - Invalid API Key
{
  "error": "Invalid API key provided"
}

// 403 - Subscription Required
{
  "error": "Access denied: Your current subscription does not include access to the Chat API (v4). Please upgrade your plan or contact your administrator."
}

Validation Errors

// 422 - Missing Required Field
{
  "error": "The 'query' field must be provided as type text."
}

// 422 - Invalid Parameter
{
  "error": "The 'embedding' array must contain exactly 512 dimensions."
}

// 422 - Out of Range
{
  "error": "Limit must be less than 100."
}

Rate Limiting

// 429 - Rate Limit Exceeded
{
  "error": "Rate limit exceeded. Please try again later.",
  "retryAfter": 60
}

Server Errors

// 500 - Internal Server Error
{
  "error": "Internal server error"
}

// 500 - Service Unavailable
{
  "error": "There was an unexpected error processing your request. Please try again."
}

SDK Examples

Node.js with Axios

const axios = require('axios');

class StyleGPTClient {
  constructor(apiKey, baseURL = 'https://stylegpt.ai') {
    this.apiKey = apiKey;
    this.baseURL = baseURL;
    this.client = axios.create({
      baseURL: this.baseURL,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      }
    });
  }

  async chat(messages, options = {}) {
    const response = await this.client.post('/api/v4/chat', {
      messages,
      ...options
    });
    return response.data;
  }

  async searchText(query, options = {}) {
    const response = await this.client.post('/api/v4/dataset/search/text', {
      query,
      ...options
    });
    return response.data;
  }

  async searchEmbedding(embedding, options = {}) {
    const response = await this.client.post('/api/v4/dataset/search/embedding', {
      embedding,
      ...options
    });
    return response.data;
  }

  async generateOutfitImage(imageUrls, modelDescription) {
    const response = await this.client.post('/api/v4/outfit/image/generate', {
      imageUrls,
      modelDescription
    });
    return response.data;
  }
}

// Usage
const client = new StyleGPTClient('your-api-key');

// Chat example
const styling = await client.chat([{
  role: 'user',
  content: [{ type: 'text', text: 'Create a summer outfit' }]
}], { useAdvancedStyling: true });

// Search example
const results = await client.searchText('red dress', {
  limit: 10,
  filters: { 'metadata.gender': 'womens' }
});

Python with Requests

import requests
import json

class StyleGPTClient:
    def __init__(self, api_key, base_url="https://stylegpt.ai"):
        self.api_key = api_key
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def chat(self, messages, **kwargs):
        response = requests.post(
            f"{self.base_url}/api/v4/chat",
            headers=self.headers,
            json={"messages": messages, **kwargs}
        )
        return response.json()
    
    def search_text(self, query, **kwargs):
        response = requests.post(
            f"{self.base_url}/api/v4/dataset/search/text",
            headers=self.headers,
            json={"query": query, **kwargs}
        )
        return response.json()
    
    def search_embedding(self, embedding, **kwargs):
        response = requests.post(
            f"{self.base_url}/api/v4/dataset/search/embedding", 
            headers=self.headers,
            json={"embedding": embedding, **kwargs}
        )
        return response.json()
    
    def generate_outfit_image(self, image_urls, model_description):
        response = requests.post(
            f"{self.base_url}/api/v4/outfit/image/generate",
            headers=self.headers,
            json={
                "imageUrls": image_urls,
                "modelDescription": model_description
            }
        )
        return response.json()

# Usage
client = StyleGPTClient("your-api-key")

# Chat example
result = client.chat([{
    "role": "user", 
    "content": [{"type": "text", "text": "Professional outfit"}]
}], useAdvancedStyling=True)

# Search example
items = client.search_text("blue jeans", limit=5)

Error Handling Best Practices

// Comprehensive error handling
async function searchWithRetry(client, query, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const results = await client.searchText(query);
      return results;
    } catch (error) {
      if (error.response) {
        const { status, data } = error.response;
        
        switch (status) {
          case 401:
            throw new Error('Authentication failed. Check your API key.');
          case 403:
            throw new Error('Subscription required. Upgrade your plan.');
          case 422:
            throw new Error(`Invalid request: ${data.error}`);
          case 429:
            if (attempt < maxRetries) {
              const delay = data.retryAfter || 60;
              console.log(`Rate limited. Retrying in ${delay} seconds...`);
              await new Promise(resolve => setTimeout(resolve, delay * 1000));
              continue;
            }
            throw new Error('Rate limit exceeded. Try again later.');
          case 500:
            if (attempt < maxRetries) {
              console.log(`Server error. Retrying attempt ${attempt}...`);
              await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
              continue;
            }
            throw new Error('Server error. Please contact support.');
          default:
            throw new Error(`Unexpected error: ${data.error}`);
        }
      }
      throw error;
    }
  }
}

Additional Resources

  • API Status: status.stylegpt.ai
  • Support: [email protected]
  • Rate Limit Increases: Contact support for enterprise rate limits
  • Webhooks: Available for real-time outfit generation notifications
  • SDKs: Official SDKs available for JavaScript, Python, PHP, and Ruby

For questions or issues, please contact our support team or check our comprehensive guides at docs.stylegpt.ai.

Ready to get started?

Test our APIs in the interactive playground or generate your API keys.

Try API PlaygroundGet API Keys