The face reading engine for modern apps.
Upload one face photo and receive structured facial features, traditional category readings, and an optional biometric mask overlay.
What is face reading?
Face reading studies facial structure, expression, proportions, and feature regions to reflect personality, temperament, life themes, and life stages. Traditions like Mian Xiang, Samudrik Shastra, and physiognomy use ideas such as the Three Courts, Twelve Palaces, and Five Elements for cultural, entertainment, and self-reflection readings. In product experiences, it can turn a simple face image into an engaging personality-style journey with category-based insights users can explore one by one.
DEEP INTERPRETATION
Face reading categories.
Give users focused readings across personality, relationships, career, wealth, wellness, and growth from one structured face scan.
FACE READING FLOW
Get face readings step by step.
Move users from photo capture to structured feature maps, category readings, and processed face overlays.
01
Scan the face image
02
Fetch a stored face feature
03
Call category readings
04
Show processed face overlay
1curl --request POST \
2 --url https://vision.astrologyapi.com/face-reading/get-face-id \
3 --header 'x-astrologyapi-key: YOUR_API_KEY' \
4 --header 'Content-Type: application/json' \
5 --data '{
6 "image_url": "https://example.com/face.jpg"
7 }'COMPREHENSIVE ENDPOINTS
Engineered for absolute detail.
A suite of highly reliable API actions tailored for high-load platforms, astrological applications, and entertainment products.
Your data
How we handle face-reading data
Understand the lifecycle of uploaded images, extracted features and the readings returned to your application.
What you send
Face images or image URLs and the inputs needed for the requested reading. Images, extracted visual information, identifiers and generated readings can form a reusable record.
Storage & deletion
Permanently deleted after approximately thirty days, including originals and backups held by AstrologyAPI. This is an approximate cycle, not a fixed day-thirty deadline.
AI & model use
AstrologyAPI never trains models on user data. Our main AI providers are OpenAI and Gemini, and we prohibit their use of customer data for their own evaluation. Provider-specific retention and processing arrangements are separate from our own storage cycle.
Only upload images you are authorised to provide. An identifier does not make a face image or its derived information anonymous.
Infrastructure & service providers
We use AWS and Google Cloud infrastructure in India and US regions, Cloudflare for DNS and website hosting, and R2 and S3 storage. These are overall infrastructure details, not exclusive residency commitments for every product, provider or backup. Service-specific arrangements belong in your agreement.
Explore service providersAdd face reading without building vision infrastructure.
Use the face-reading route for your CTAs now, then connect the full developer docs when the section is ready.
Frequently Asked Questions
Our Face Reading API analyzes a single facial photograph using AI and traditional face reading principles to extract facial features and generate structured insights about personality, career, wealth, relationships, health, luck, and more. It returns JSON responses that can be easily integrated into any application.
Upload a clear, front-facing photograph of a single real person in JPG, JPEG, or PNG format (maximum 5 MB). The API automatically rejects blurry images, multiple faces, cartoons, drawings, or images where no face is detected.
The API provides detailed readings across multiple categories including Personality, Career, Wealth, Love, Marriage, Health, Family, Luck, Wisdom, and Challenges. It also returns structured facial features such as face shape, eyes, nose, forehead, chin, symmetry, and facial landmarks.
Yes. The Mask Outline Image endpoint creates a processed facial overlay with mask outline data and detected traits. This image can be displayed alongside the generated reading to improve user engagement.
The API combines modern computer vision with traditional face reading systems such as Mian Xiang and Samudrik Shastra. The readings are intended for entertainment, self-reflection, and wellness applications rather than scientific or medical diagnosis.
Absolutely. The API is REST-based and returns structured JSON, making it easy to integrate into mobile apps, websites, SaaS platforms, astrology applications, wellness products, and AI-powered experiences.
Simply send a facial image to the scanning endpoint. The API returns a unique face_id, which can then be used to fetch facial features, category-wise readings, or the processed facial overlay without uploading the image again.
Yes. Images and extracted facial data are securely stored to support subsequent API requests. Authentication is required for all protected endpoints, and integrations are designed with secure API access in mind.