Skip to content
96Astro API

Blog

Palm Reading API: how to add AI palmistry to your app

· 96Astro API team · 9 min read · Photo readings, Guides

A stylized palm and luminous lines illustrate photo-based palmistry.

A practical guide to AI palm reading APIs: hand type, palm lines, mounts and life readings from one photo, traced lines, compatibility, costs and privacy.

In brief

  • A palm reading API turns one photo of a hand into a structured reading: hand type, fingers, the major and minor lines, the mounts, special marks and life-area readings such as career, love and money.
  • With the 96Astro API you send the photo with each call. It is not stored, and the person in the photo must have agreed.
  • You can ask for one section, the whole reading in a single call, a question of your own, a compatibility reading from two palms, or the traced lines to draw over the photo.
  • Readings are for reflection. They must not predict illness, life span, marriage counts or divorce; no photo establishes those outcomes. Validate outputs against those restrictions.

Palmistry can add a photo-based feature to an astrology app, but it needs careful input handling. A hand photo is messy input: different lighting, rings, partial fingers, a tilted camera. This guide explains how an AI palm reading API works, what it can and cannot tell you, how to design the screens around it, and how to keep costs and privacy under control.

What a palm reading API actually does

A palm reading API is a vision model with a carefully written brief. It looks at the photo, reports what it can see (the observations), and then reads those observations in the language of traditional palmistry. A good API keeps those two parts separate, so your users can see why a reading says what it says.

With the 96Astro API every palmistry section comes back in the same shape:

FieldWhat it holds
observedWhat the model saw in this photo, as short statements
readingThe palmistry reading of those observations
adviceOne practical suggestion

Keeping the observations visible matters. If a user's heart line is faint in the photo, the reading says so instead of inventing detail. When the photo cannot be read at all, the call returns 422 image_not_usable and nothing is charged.

The palmistry endpoints, and when to use each

The palmistry family has eighteen capabilities. They fall into five groups.

GroupCapabilitiesUse it for
The handpalm-hand-type, palm-fingers, palm-major-lines, palm-minor-lines, palm-mounts, palm-special-featuresA structural read of the palm, section by section
Life areaspalm-personality, palm-career, palm-money, palm-love, palm-marriage, palm-health, palm-challenges, palm-luckReadings people actually share and pay for
Everything at oncepalm-readingEvery section for the cost of one model call
Your own questionpalm-question"What does my head line say about how I make decisions?"
Two peoplepalm-compatibilityA couple's reading from two palm photos
Drawingpalm-lines-imageThe life, head, heart and fate lines as points, with a confidence for each

Choosing between palm-reading and single sections. If you show several sections to the same person, palm-reading is the cheaper route: it returns every section for one model call. Keep the answer and reveal parts of it as the user moves through your screens. Single sections suit an "unlock one reading" model, where each tap is a separate purchase.

Your first palm reading request

Make the photo smaller in the browser first (we recommend the longest side at 1,280 to 1,600 pixels as a JPEG), then send it as base64:

curl https://api.96astroapi.com/v1/palmistry/palm-reading \
  -H "Authorization: Bearer $ASTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "<base64 of the JPEG>",
    "mime_type": "image/jpeg",
    "consent": true,
    "language": "hi",
    "tier": "fast"
  }'
FieldRequiredNotes
image_base64YesPNG, JPEG or WebP, at most 3.75 MiB once decoded. A data:image/...;base64, prefix is accepted
mime_typeUnless a data: URIMust match the file
consentYesMust be true: the person agreed, and is an adult or has a guardian's agreement
languageNoThe language of the reading
tierNofast (the default) or balanced, a stronger model at a higher price

Use a sandbox key (sk_test_...) while you build. Sandbox calls are free, and the Palm and face readings guide lists every field.

Tracing the palm lines over the photo

Users love seeing their own lines highlighted. palm-lines-image returns each line as a list of points on a 0 to 1000 grid, a confidence between 0 and 1, and an overlay_svg that holds only the marks:

{
  "data": {
    "lines": [
      { "name": "life",  "points": [[420, 380], [360, 520], [380, 700], [470, 860]], "confidence": 0.9 },
      { "name": "heart", "points": [[300, 400], [500, 340], [720, 370]], "confidence": 0.8 }
    ],
    "coordinate_space": { "width": 1000, "height": 1000, "origin": "top left" }
  }
}

Lay the SVG over your own copy of the photo, stretched to the image's box. The API never sends the photo back. A before-and-after slider (the original photo on one side, the traced lines on the other) is the simplest way to make this feel magical, and the confidence bars stop users from over-reading a faint line.

Designing the palm reading screens

The palm reading screen in the 96Astro dashboard follows a flow you can copy:

  1. Upload, with guidance. Show the six rules that make or break a reading: use the dominant hand, palm open and flat, fingers together and in view, bright even light without flash glare, rings and watches off, the palm and wrist filling the frame.
  2. Consent, as its own step. A checkbox that says the person in the photo agreed, with a sentence on what happens to the photo. Do not hide it in your terms.
  3. Scan and trace. Run palm-lines-image first. It can check whether tracing is usable, but it is a separate metered call when successful; show its estimated cost before running it.
  4. The hand. Six structural cards (hand type, fingers, major lines, minor lines, mounts and special marks), each with a Run button and a Run all.
  5. Readings. Eight life-area cards. Open one to read it in full.
  6. Ask and compare. A free-text question, and a second photo for compatibility.

Save every result on the device, keyed to the photo, so reopening a palm costs nothing. Show the credits each reading used. Users trust a product more when they can see what they are paying for.

What a palm reading API should never tell you

This is where products get into trouble. A photo of a hand cannot show how long someone will live, how many times they will marry, whether they will divorce, or anything about their sexual or physical health. Our model is instructed never to say these things, and your interface should never imply them either.

The model is also told never to identify a person and never to infer race, religion, caste, sexuality, disability or age. Readings must not be used for hiring, lending, insurance or any decision about a person. Treat them as reflection and entertainment, and say so in your app.

Compatibility from two palms

palm-compatibility takes image_base64 and second_image_base64. As well as the reading sections, it returns a compatibility object:

FieldMeaning
score0 to 100
levelA word for the score
headlineOne line to show first
element_matchHow the two hand elements combine
first_person, second_personEach with love_style, brings and needs

A model judges these from what it can see, so present the score as a talking point for the couple, not a verdict. Both people must agree to their photos being read.

What palm reading costs

Palm and face readings are metered by model cost, the same way as AI readings, using the vision tier you choose. The fast tier is the right default. Three things keep costs low:

  • Use palm-reading for multi-section screens. One model call, every section.
  • Cache by photo. A saved response can be reused; a fresh model call can differ. Include photo hash, consent scope, language, tier and model or prompt version in the cache key.
  • Check the photo first. palm-lines-image or a cheap single section confirms the photo is usable before a user buys a bundle.

A photo the model cannot read is never charged.

Turning a reading into a PDF

People like something to keep. Send the reading you already have to a PDF job and you get a designed report without sending the photo again. See A PDF of a palm or face reading. A palm report is a natural paid add-on after a free reading.

Privacy checklist for a palm reading feature

  • The API forwards the photo to a model provider. Review provider retention terms as well as your own storage, logs and analytics; application-level non-storage is not a guarantee of zero third-party retention.
  • Keep your own copy only if your users agreed to it, and let them delete it.
  • Never accept photos of children without a guardian's agreement.
  • Say plainly that it is an AI reading of a photo, for reflection.
  • Check the rules in each country you sell in: in many places a hand photo is personal data.

Ideas for palm reading features

  • A free first reading, personality or hand type, with the other life areas unlocked one by one.
  • A couple's reading for a dating or wedding app, with both people's consent.
  • An "ask your palm" box for curious users who have one question.
  • A printable palm report as a paid product.
  • Palm plus chart. Show the palm reading next to the person's birth chart from the Kundli API. Keep the two traditions clearly labelled; agreement between generated narratives is not independent evidence of accuracy.

Frequently asked questions

Do you store the palm photos?

The application does not intentionally store the photo as a report asset; it is sent to a vision provider whose retention terms must also be reviewed. If you want a PDF later, send the reading you already have, not the photo.

Which hand should users photograph?

The dominant hand, the one they write with, is the usual choice in palmistry. Some traditions read both. You can run two readings and present them side by side.

What happens if the photo is blurry or not a palm?

The API returns 422 image_not_usable with a reason, and nothing is charged. Show the reason and the photo tips again.

Does the palm reading API predict health or life span?

No, on purpose. No photo can show these things, and saying so could cause real harm. The intended contract forbids life expectancy, marriage counts and divorce probabilities. Check outputs and suppress prohibited claims rather than relying on prompt instructions alone.

Can I use palm reading for matchmaking decisions?

Use palm-compatibility as a fun, consented feature for a couple. Readings must not be used to decide anything about a third party, such as hiding profiles or rejecting matches.

Which languages are supported?

Readings come in the languages listed on the palm reading API page, including Hindi, Bengali, Gujarati, Tamil, Telugu and major European languages.

Can I try it without writing code?

Yes. Sign in to the dashboard and open Palm reading: upload a photo, trace the lines and run any reading with a sandbox key.

Get started

Create a free sandbox key, open the Palm Reading API page for examples in seven languages, and read the palm reading guide for a complete build. Sandbox calls are free, so you can design the whole flow before you spend a credit.

Get the next guide by email

One email a month with new guides and API changes. No account needed.

About once a month: new guides, API features and astrology-developer news. We email a confirmation link first; unsubscribe with one click from any newsletter. See our privacy policy.

Send us feedback

What is it about?