Integrate AI-powered face shape detection into your applications. Production-ready REST API with comprehensive documentation.
Make your first API call with a simple cURL command
curl -X POST https://myfaceshape.online/api/v1/analyze \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"imageBase64": "data:image/jpeg;base64,/9j/4AAQ...",
"language": "en"
}'
Replace YOUR_API_KEY
with your actual API key.
Contact api@myfaceshape.online to
get your key.
All requests require a valid API key in the headers
X-API-Key: your_api_key_here| Header | Value | Description |
|---|---|---|
| X-API-Key | string | Your unique API key for authentication |
| Content-Type | string | Must be application/json |
Complete documentation for all available endpoints
Analyze a face image to determine face shape. Returns detailed analysis including face shape classification, confidence score, style recommendations, and celebrity matches.
| Parameter | Type | Description |
|---|---|---|
| imageBase64 required* | string | Base64 encoded image with data URI prefix (max 5MB) |
| landmarks optional | object | Facial landmarks for fallback analysis (alternative to image) |
| language optional | string | Response language code. Default: "en" |
* Either imageBase64 or landmarks is required.
{
"success": true,
"data": {
"face_shape": "oval",
"confidence_percentage": 92,
"archetype": "The Classic Beauty",
"scientific_name": "Facies Ovalis",
"shape_rarity": "Common (45% of population)",
"detailed_measurements": {
"forehead_classification": "average",
"cheekbone_prominence": "moderate",
"jawline_angle": "soft",
"face_length_ratio": "balanced"
},
"style_recommendations": {
"hairstyles": {
"best_styles": ["Layered cut", "Side-swept bangs"],
"styles_to_avoid": ["Severe center parts"]
},
"eyewear": {
"ideal_frames": ["Aviator", "Wayfarer", "Cat-eye"],
"frames_to_avoid": ["Oversized square frames"]
}
},
"celebrity_matches": [
{"name": "Angelina Jolie", "why_similar": "Similar bone structure"}
],
"shareable_headline": "You Have The Classic Beauty Face"
},
"meta": {
"processing_time_ms": 1234,
"language": "en",
"analysis_type": "vision"
},
"notice": {
"powered_by": "MyFaceShape.online",
"attribution": "Powered by MyFaceShape.online - AI Face Shape Analysis",
"requirement": "Free tier usage requires a visible backlink."
}
}Health check endpoint. Use this to verify API availability. No authentication required.
{
"status": "healthy",
"timestamp": "2026-01-08T17:00:00.000Z",
"version": "1.0.0",
"api": "MyFaceShape Developer API"
}Get API information including available endpoints and rate limits. No authentication required.
Choose the plan that fits your needs
per month
coming soon
Free tier usage requires a visible backlink to MyFaceShape.online in your application. This helps us continue providing free access to our API.
Ready-to-use code snippets for popular languages
import requests
import base64
# Load and encode image
with open("face.jpg", "rb") as f:
image_data = base64.b64encode(f.read()).decode()
response = requests.post(
"https://myfaceshape.online/api/v1/analyze",
headers={
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY"
},
json={
"imageBase64": f"data:image/jpeg;base64,{image_data}",
"language": "en"
}
)
result = response.json()
print(f"Face Shape: {result['data']['face_shape']}")
print(f"Confidence: {result['data']['confidence_percentage']}%")const axios = require('axios');
const fs = require('fs');
// Load and encode image
const imageData = fs.readFileSync('face.jpg');
const base64Image = imageData.toString('base64');
const response = await axios.post(
'https://myfaceshape.online/api/v1/analyze',
{
imageBase64: `data:image/jpeg;base64,${base64Image}`,
language: 'en'
},
{
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'YOUR_API_KEY'
}
}
);
console.log(`Face Shape: ${response.data.data.face_shape}`);
console.log(`Confidence: ${response.data.data.confidence_percentage}%`);Common error responses and how to handle them
| Status | Error | Description |
|---|---|---|
| 400 | Missing input | No image or landmarks provided in request body |
| 400 | Image too large | Image exceeds 5MB limit. Compress or resize. |
| 401 | Authentication required | Missing X-API-Key header |
| 401 | Invalid API key | The provided API key is not recognized |
| 429 | Rate limit exceeded | Daily request limit reached. Wait for reset. |
| 500 | Analysis failed | Server processing error. Retry or contact support. |
Get your free API key and start integrating face shape detection into your application today.