Blog
Palm Reading API: how to add AI palmistry to your app
· 96Astro API team · 9 min read · Photo readings, Guides

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:
| Field | What it holds |
|---|---|
observed | What the model saw in this photo, as short statements |
reading | The palmistry reading of those observations |
advice | One 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.
| Group | Capabilities | Use it for |
|---|---|---|
| The hand | palm-hand-type, palm-fingers, palm-major-lines, palm-minor-lines, palm-mounts, palm-special-features | A structural read of the palm, section by section |
| Life areas | palm-personality, palm-career, palm-money, palm-love, palm-marriage, palm-health, palm-challenges, palm-luck | Readings people actually share and pay for |
| Everything at once | palm-reading | Every section for the cost of one model call |
| Your own question | palm-question | "What does my head line say about how I make decisions?" |
| Two people | palm-compatibility | A couple's reading from two palm photos |
| Drawing | palm-lines-image | The 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"
}'
| Field | Required | Notes |
|---|---|---|
image_base64 | Yes | PNG, JPEG or WebP, at most 3.75 MiB once decoded. A data:image/...;base64, prefix is accepted |
mime_type | Unless a data: URI | Must match the file |
consent | Yes | Must be true: the person agreed, and is an adult or has a guardian's agreement |
language | No | The language of the reading |
tier | No | fast (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:
- 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.
- 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.
- Scan and trace. Run
palm-lines-imagefirst. It can check whether tracing is usable, but it is a separate metered call when successful; show its estimated cost before running it. - 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.
- Readings. Eight life-area cards. Open one to read it in full.
- 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:
| Field | Meaning |
|---|---|
score | 0 to 100 |
level | A word for the score |
headline | One line to show first |
element_match | How the two hand elements combine |
first_person, second_person | Each 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-readingfor 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-imageor 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.
Keep reading
- How to monetise an astrology app: models and cost scenarios
12 November 2026 · 9 min read
- Face Reading API: responsible AI face reading for apps
12 November 2026 · 7 min read
- Vastu API: automated Vastu Shastra floor plan analysis
12 November 2026 · 7 min read



