/get-face-idUpload a photo
Send an image URL, a file or base64. We check the photo and return a face_id.
1{ 2 "status": true, 3 "message": "success", 4 "data": { "face_id": "a1b2c3d4e5f6" } 5}
Upload one face photo and receive structured facial features, traditional category readings, and an optional biometric mask overlay.

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
Give users focused readings across personality, relationships, career, wealth, wellness, and growth from one structured face scan.
FACE READING FLOW
Move users from photo capture to structured feature maps, category readings, and processed face overlays.
01
02
03
04
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
A suite of highly reliable API actions tailored for high-load platforms, astrological applications, and entertainment products.
Your data
Understand the lifecycle of uploaded images, extracted features and the readings returned to your application.
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.
Permanently deleted after approximately thirty days, including originals and backups held by AstrologyAPI. This is an approximate cycle, not a fixed day-thirty deadline.
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.
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 providersOur Face Reading API reads one clear face photo. It maps the face, records each feature and writes readings based on face reading traditions such as Mian Xiang and Samudrik Shastra.
You upload the photo once and get a face_id. After that, every feature and reading is one small call with that id. You never send the image again.
One upload gives you an id you can reuse for every later call.
Face shape, eyes, nose, mouth, cheeks, chin, jaw, ears, skin and facial hair.
How symmetric the face is and how its main sections relate.
Personality, career, wealth, love, marriage, family, health, luck, wisdom and challenges.
A processed image with a mask outline you can show next to the reading.
Every response uses the same status and data shape, ready for your UI.
Every call is a POST with your key in the x-astrologyapi-key header. Start with get-face-id, then pass the face_id to any other endpoint.
Base URL: https://vision.astrologyapi.com/face-reading
/get-face-idSend an image URL, a file or base64. We check the photo and return a face_id.
1{ 2 "status": true, 3 "message": "success", 4 "data": { "face_id": "a1b2c3d4e5f6" } 5}
/shapeReturns the stored face shape. Sister endpoints cover the eyes, nose, mouth, ears and more.
Read the face shape reference →/personalityOne of ten category readings. Career, wealth, love and the rest work the same way.
1{ 2 "status": true, 3 "data": { 4 "essence": "A grounded, observant nature with quiet drive.", 5 "core_traits": ["patient", "loyal", "practical"] 6 } 7}
/mask-outline-imageReturns a link to a processed face image with a mask outline and a few impression traits.
1{ 2 "status": true, 3 "data": { 4 "processed_image_url": "https://cdn.example.com/processed-face.png", 5 "traits": { 6 "approachability": { "score": 8, "note": "warm impression" } 7 } 8 } 9}
Face reading works well as a fun, visual feature. It is meant for entertainment and self-reflection, not for identity checks or medical advice.
Add a photo-based reading next to birth charts and palm reading. Users can try it in seconds.
How to monetize face reading →Offer a personality reading as a first step in onboarding or a daily reflection prompt.
Turn a selfie into a shareable reading and a face overlay image.
Add a light love and personality reading to profiles as an icebreaker.
Astrology features for dating apps →Give your assistant structured face features so it can talk about them with care.
Use the same account for face reading and 300+ astrology endpoints.
Astrology JSON API →Follow the reference to make your first face reading call.
Upload one photo, get a face_id, and call any of ten readings. We handle face detection, feature mapping and the reading text.
Send your API key in the x-astrologyapi-key header on every request. Make the calls from your server so the key stays private.
There are ten category readings: personality, career, wealth, love, marriage, family, health, luck, wisdom and challenges. You can also fetch single features such as face shape, eyes, nose, mouth, ears, symmetry and proportions.
Create a free account to get your API key. Then upload one photo to get a face_id and call any reading with it. Each endpoint has its own credit cost, shown on our pricing page.
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.