Beauty scan API: a complete beauty profile from one selfie

What a selfie skin analysis is — and what it is not

A skin analysis from a photo uses computer vision to read, in an ordinary phone selfie, the attributes a store consultant would observe in person: the skin tone and its undertone (warm, cool or neutral) and — in MaIA Scan's case — also the hair colour and the hair type (straight, wavy, curly or coily). The result is not a report: it is a structured beauty profile, built to personalise product recommendations, quizzes and customer service.

MaIA Scan does not do facial recognition. The API does not identify people, create biometric templates, match faces, infer protected traits or issue medical diagnoses. Every attribute comes back with a status — predicted or abstained — and a score, and the guidance is simple: when the model abstains or the score is low, the brand confirms with the customer instead of assuming.

What sets the model apart is what it was trained on: hundreds of thousands of real selfies from Brazilian consumers, covering the full range of Brazilian skin tones and hair types — not a mostly white dataset. That is why MaIA Scan is uniquely strong for Brazilian and Latin American skin, precisely where most skin analysis APIs get the foundation shade wrong.

How it works, in four steps

The call is synchronous: the response to the request is the finished profile.

1. 1

   The customer consents and sends a selfie

   One front-facing photo in JPEG or PNG up to 6 MB — plus, for more precision on hair, a side photo in the same call at no extra credit. Consent is collected beforehand, by the brand.

2. 2

   Your application calls POST /api/v1/scan

   Multipart with the front field (and the optional side), authenticated with the account key: Authorization: Bearer msk_live_…. An optional x-request-id rides along on the usage event.

3. 3

   The API reserves the credit and analyses

   The credit is reserved before we call the model and settled when the answer arrives. If the analysis fails, the reservation is released automatically — you never pay for a result you did not receive.

4. 4

   The profile comes back as JSON, with a status on every attribute

   session_id, request_id, credits_charged, credits_remaining and the result document with the attributes you requested — each with status, value, score and model version — plus the photo-quality check. You decide what to show, what to confirm and what to feed into your rules.

What the beauty attributes API returns

Four visible attributes, grouped in three models you pick per request with the models field. Only requested attributes come back; keys follow the MaIA Scan API version — treat the response as a JSON document and read the fields you need.

Who it is for: where a photo-based beauty profile changes the sale

MaIA Scan is a building block. What you do with the profile depends on the channel — and that is where selfie skin analysis for e-commerce turns into revenue.

Why MaIA Scan rather than a generic skin analysis API

• Trained where beauty is diverse: hundreds of thousands of real Brazilian selfies, across the full range of Brazilian skin tones and hair types.
• In production at Latin America's largest beauty clubs — glam and Men's Market — on the same engine you integrate through the API.
• Skin and hair in one call: hair analysis from a selfie (colour and structure) comes along, with no second vendor.
• Three model families — colour, skin condition and hair structure — retrained with new data and human validation; the response records model and pipeline versions.
• Privacy by design: mandatory consent, raw-image retention configurable per project, no facial recognition.
• From profile to recommendation: with MaIA Beauty Advisor the same profile becomes product suggestions from your catalogue, with the reason why.

Credits: pay for what you use, no subscription

Every analysis consumes credits from the account balance according to the models you ask for — skin (tone and undertone), hair colour and hair type — and only for those that returned a value; the optional side photo goes in the same call. Packages are sold by number of credits — Starter (R$ 998 for 500), Growth (R$ 1,998 for 2,500) and Scale (R$ 4,998 for 10,000) — paid by card, Pix or boleto in our own checkout. One-off and automatic top-ups follow your last paid package; credits never expire. The per-operation price list and the full documentation PDF live in the account area.

Every successful response carries the remaining balance (credits_remaining). With a zero balance the call is refused before any processing with 402 insufficient_credits, at no charge. For enterprise volumes, per-key limits or a contract, talk to us.

Privacy, consent and LGPD

You are responsible for obtaining the person's explicit authorisation before sending any photo. In the gateway the image stays in memory only for the duration of the request and is forwarded once to the model — nothing goes to disk, database or logs. The MaIA Scan API stores the structured result with model and pipeline versions; raw-image retention is configurable per project. per request we keep account, key, endpoint, status, credit, latency, x-request-id and capture_id — what you see on your usage page.

Integration: self-service today, a project when you want more

The analysis is self-service via API. Product recommendation from the profile is not an endpoint: it is delivered as a project, and it is quick to set up — we integrate your brand's catalogue.