✋ Palmistry API and 🎧 Audio Reports API are now live. Ship them in your app today.
AI FACE READING API

Face Reading API: one photo, ten readings in JSON.

Upload one face photo and receive structured facial features, traditional category readings, and an optional biometric mask overlay.

Face reading categories preview

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

Scan the face image
200
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  }'
AstrologyAPI

Your data

How we handle face-reading data

Understand the lifecycle of uploaded images, extracted features and the readings returned to your application.

About 30 daysFace data deletion cycle
Privacy & your rights
  1. 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.

  2. 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.

  3. 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 providers

What the Face Reading API returns

Our 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.

  • A face_id

    One upload gives you an id you can reuse for every later call.

  • Facial features

    Face shape, eyes, nose, mouth, cheeks, chin, jaw, ears, skin and facial hair.

  • Balance and proportions

    How symmetric the face is and how its main sections relate.

  • Ten category readings

    Personality, career, wealth, love, marriage, family, health, luck, wisdom and challenges.

  • A face overlay image

    A processed image with a mask outline you can show next to the reading.

  • Clean JSON

    Every response uses the same status and data shape, ready for your UI.

Key Face Reading endpoints

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

POST/get-face-id

Upload 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}
Read the /get-face-id reference →
POST/personality

Personality reading

One 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}
Read the /personality reference →
POST/mask-outline-image

Face overlay image

Returns 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}
Read the /mask-outline-image reference →

Who uses the Face Reading API

Face reading works well as a fun, visual feature. It is meant for entertainment and self-reflection, not for identity checks or medical advice.

Astrology apps

Add a photo-based reading next to birth charts and palm reading. Users can try it in seconds.

How to monetize face reading →

Wellness and self-discovery apps

Offer a personality reading as a first step in onboarding or a daily reflection prompt.

Social and entertainment apps

Turn a selfie into a shareable reading and a face overlay image.

Dating apps

Add a light love and personality reading to profiles as an icebreaker.

Astrology features for dating apps →

AI chat products

Give your assistant structured face features so it can talk about them with care.

Multi-feature astrology platforms

Use the same account for face reading and 300+ astrology endpoints.

Astrology JSON API →

Add face reading without building vision infrastructure.

Upload one photo, get a face_id, and call any of ten readings. We handle face detection, feature mapping and the reading text.

Face Reading API FAQ

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.