Beauty Analysis API

Integrate advanced facial analysis and beauty recommendations into your applications.

API Features

  • Face detection & 468-point landmark analysis
  • Comprehensive facial observations
  • Technical overlay generation
  • Treatment recommendations
  • Product recommendations
  • Batch analysis processing
  • OpenAI Vision integration
  • No payment barriers

API Quick Links

Authentication

All API requests require authentication using an API key. All features are available with a valid API key - no payment barriers!

Contact us to obtain your unique API key and partner ID.
Authentication Headers

Include your API key and partner ID in the request headers:

X-API-Key: your_api_key_here
X-Partner-ID: your_partner_id_here
Example Authentication
curl -X POST https://your-domain.com/api/v2/analyze \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Partner-ID: your_partner_id_here" \
  -F "image=@face.jpg"
Full Feature Access
  • 468-point facial landmark detection
  • Comprehensive facial observations
  • Technical overlay generation
  • Treatment recommendations (PMU, skincare, cosmetic)
  • Product recommendations
  • Batch analysis processing
  • OpenAI Vision integration
  • All features included - no restrictions!

API Endpoints

POST /api/v2/analyze

Perform comprehensive facial analysis with 468-point landmark detection, feature metrics, and visual overlay generation.

Request Parameters
Parameter Type Status Description
image File Required The facial image to analyze (JPEG, PNG, WebP)
image_reference String Optional A reference identifier for the image
includeTechnicalOverlay Boolean Optional Include technical overlay with landmarks (default: true)
overlayStyle String Optional Overlay style: basic, professional, detailed, research
Example Request
curl -X POST https://your-domain.com/api/v2/analyze \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Partner-ID: your_partner_id_here" \
  -F "image=@face.jpg" \
  -F "image_reference=user_123_photo" \
  -F "includeTechnicalOverlay=true" \
  -F "overlayStyle=professional"
Example Response
200 OK
{
  "success": true,
  "analysis_id": "12345",
  "image_url": "https://cdn.example.com/analysis/image.jpg",
  "features": {
    "left_eyebrow": {
      "confidence": 0.95,
      "bbox": {"x": 100, "y": 50, "w": 80, "h": 25},
      "landmarks": [[110, 55], [120, 52], ...],
      "metrics": {
        "thickness": 0.82,
        "arch": 0.75,
        "symmetry": 0.89
      }
    }
  },
  "technicalOverlay": {
    "overlayImageBase64": "data:image/png;base64,iVBORw0KGgo...",
    "overlayImageUrl": "https://cdn.example.com/overlay.png",
    "totalLandmarks": 468,
    "averageConfidence": 0.93
  }
}
POST /api/v2/observations

Get detailed facial observations and measurements from an uploaded image.

Example Response
200 OK
{
  "success": true,
  "observations": {
    "eyebrows": {
      "shape": "arched",
      "thickness": "medium",
      "symmetry_score": 0.87,
      "recommendations": ["Consider micro-shading for fuller appearance"]
    },
    "eyes": {
      "shape": "almond",
      "openness": 0.78,
      "color_analysis": {"hue": 45, "saturation": 0.6}
    }
  }
}
GET /api/v2/analysis/{analysis_id}/treatments

Get personalized treatment recommendations based on facial analysis.

Query Parameters
category String Optional Filter by category: pmu, skincare, cosmetic
priority String Optional Filter by priority: high, medium, low
Example Response
200 OK
{
  "success": true,
  "treatments": [
    {
      "category": "pmu",
      "title": "Microblading Eyebrows",
      "description": "Enhance natural brow shape with hair-like strokes",
      "priority": "high",
      "healing_time": "4-6 weeks",
      "expected_results": "Fuller, more defined eyebrows"
    }
  ]
}
GET /api/v2/analysis/{analysis_id}/products

Get personalized product recommendations based on facial analysis.

Example Response
200 OK
{
  "success": true,
  "products": [
    {
      "category": "eyebrow",
      "name": "Precision Brow Pencil",
      "description": "Define and fill sparse areas",
      "shade_recommendation": "Medium Brown",
      "application_tips": ["Use light strokes", "Blend with spoolie"]
    }
  ]
}
GET /api/v2/analysis/{analysis_id}/technical-overlay

Get technical overlay with 468-point landmarks for existing analysis.

Query Parameters
style String Optional Overlay style: basic, professional, detailed, research
showConfidence Boolean Optional Show confidence scores on overlay
Example Response
200 OK
{
  "success": true,
  "technicalOverlay": {
    "overlayImageBase64": "data:image/png;base64,iVBORw0KGgo...",
    "overlayImageUrl": "https://cdn.example.com/overlay.png",
    "imageWidth": 800,
    "imageHeight": 600,
    "processingTime": 1.23
  },
  "overallMetrics": {
    "totalLandmarks": 468,
    "averageConfidence": 0.93,
    "symmetryScore": 0.85
  }
}
GET /api/recommendations/{analysis_id}

Retrieve premium PMU recommendations based on a previous analysis. Requires payment verification.

This endpoint requires payment verification and access to premium features.
Path Parameters
Parameter Type Description
analysis_id String The ID of a previously performed analysis
Headers
Header Required Description
X-API-Key Yes Your API key
X-Partner-ID Yes Your partner ID
X-Payment-Token Yes Payment verification token
Example Request
curl -X GET https://beautyanalysis.com/api/recommendations/12345 \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Partner-ID: your_partner_id_here" \
  -H "X-Payment-Token: payment_verification_token_here"
Example Response
200 OK
{
  "analysis_id": "12345",
  "recommendations": {
    "eyebrows": {
      "title": "Ombré Powder Brows",
      "description": "A soft, powdered effect that mimics the look of makeup with a more defined tail.",
      "technique": "Pixel/Powder Shading",
      "healing_time": "7-10 days",
      "confidence": 0.92
    },
    "lips": {
      "title": "Lip Blush",
      "description": "A subtle enhancement of natural lip color with definition.",
      "technique": "Watercolor Blending",
      "healing_time": "5-7 days",
      "confidence": 0.88
    },
    "eyeliner": { ... }
  },
  "personalized_insight": "Your facial features suggest elegant, symmetrical eyebrows would enhance your overall look. Based on your skin tone and facial structure, a soft powder ombré technique would create the most natural enhancement..."
}
401 Unauthorized
{
  "error": "Invalid or missing payment verification",
  "code": "PAYMENT_VERIFICATION_FAILED"
}
POST /api/verify-payment

Verify a payment and obtain a payment verification token for accessing premium features.

Request Parameters
Parameter Type Status Description
payment_id String Required The Stripe payment ID or intent ID
analysis_id String Required The analysis ID associated with the payment
Example Request
curl -X POST https://beautyanalysis.com/api/verify-payment \
  -H "X-API-Key: your_api_key_here" \
  -H "X-Partner-ID: your_partner_id_here" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pi_3NKM9lHf3F7YsE791oYeXaBC",
    "analysis_id": "12345"
  }'
Example Response
200 OK
{
  "verified": true,
  "payment_token": "pmt_ver_9a8b7c6d5e4f3g2h1i",
  "expires_at": "2025-06-24T21:27:26Z"
}
400 Bad Request
{
  "verified": false,
  "error": "Invalid payment ID or payment not found",
  "code": "INVALID_PAYMENT"
}

Code Samples

// JavaScript example using fetch API

// 1. Analyze an image
async function analyzeImage(imageFile, userReference) {
  const formData = new FormData();
  formData.append('image', imageFile);
  formData.append('user_reference', userReference);

  const response = await fetch('https://beautyanalysis.com/api/analyze', {
    method: 'POST',
    headers: {
      'X-API-Key': 'your_api_key_here',
      'X-Partner-ID': 'your_partner_id_here'
    },
    body: formData
  });

  return response.json();
}

// 2. Get premium recommendations
async function getRecommendations(analysisId, paymentToken) {
  const response = await fetch(`https://beautyanalysis.com/api/recommendations/${analysisId}`, {
    method: 'GET',
    headers: {
      'X-API-Key': 'your_api_key_here',
      'X-Partner-ID': 'your_partner_id_here',
      'X-Payment-Token': paymentToken
    }
  });

  return response.json();
}
# Python example using requests
import requests

# 1. Analyze an image
def analyze_image(image_path, user_reference):
  url = 'https://beautyanalysis.com/api/analyze'
  headers = {
    'X-API-Key': 'your_api_key_here',
    'X-Partner-ID': 'your_partner_id_here'
  }
  files = {
    'image': open(image_path, 'rb')
  }
  data = {
    'user_reference': user_reference
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  return response.json()

# 2. Get premium recommendations
def get_recommendations(analysis_id, payment_token):
  url = f'https://beautyanalysis.com/api/recommendations/{analysis_id}'
  headers = {
    'X-API-Key': 'your_api_key_here',
    'X-Partner-ID': 'your_partner_id_here',
    'X-Payment-Token': payment_token
  }

  response = requests.get(url, headers=headers)
  return response.json()
// PHP example using cURL

// 1. Analyze an image
function analyzeImage($imagePath, $userReference) {
  $url = 'https://beautyanalysis.com/api/analyze';
  $curl = curl_init();

  $postFields = array(
    'image' => new CURLFile($imagePath),
    'user_reference' => $userReference
  );

  curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $postFields,
    CURLOPT_HTTPHEADER => array(
      'X-API-Key: your_api_key_here',
      'X-Partner-ID: your_partner_id_here'
    )
  ));

  $response = curl_exec($curl);
  curl_close($curl);

  return json_decode($response, true);
}

// 2. Get premium recommendations
function getRecommendations($analysisId, $paymentToken) {
  $url = "https://beautyanalysis.com/api/recommendations/{$analysisId}";
  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => array(
      'X-API-Key: your_api_key_here',
      'X-Partner-ID: your_partner_id_here',
      'X-Payment-Token: ' . $paymentToken
    )
  ));

  $response = curl_exec($curl);
  curl_close($curl);

  return json_decode($response, true);
}

Error Codes

Error Code Description
AUTHENTICATION_FAILED Invalid or missing API key or partner ID
INVALID_REQUEST Missing required parameters or invalid request format
NO_FACE_DETECTED No face was detected in the provided image
MULTIPLE_FACES Multiple faces detected in the image
ANALYSIS_NOT_FOUND The specified analysis ID was not found
PAYMENT_VERIFICATION_FAILED Invalid or missing payment verification
INVALID_PAYMENT The payment ID provided is invalid or not found
SERVER_ERROR Internal server error

Need Help?

If you have any questions about the API or need assistance with integration, please contact our API support team:

Contact API Support