MaIA API: skin and hair analysis from a selfie and a makeup simulator, over HTTP.

Overview

The MaIA API is the HTTPS gateway B4A exposes at maiascan.ai for the photo-based MaIA products. You authenticate with a key from your account, send a photo as multipart/form-data and get the answer synchronously: a beauty profile in JSON (MaIA Scan — skin tone and undertone, hair colour and hair type, choosing which models to run) or the same photo as a PNG with the product applied (MaIA Try-On — lipstick in preset shades or any colour of your brand, and foundation as a makeup simulator). The models are experimental: the response carries a status per attribute and flags when the person should confirm the result.

Nothing is assumed about your stack: any HTTP client that can send multipart works. No mandatory SDK, no webhook, no session state — the response of the call is the result. The analysis is cosmetic and photo-based: it is not a diagnosis, does no facial recognition and does not identify people.

Start in four steps

1. 1

   Create the account

   Sign in with Google, e-mail and password, or receive a magic link by e-mail. No manual approval — and the full documentation PDF, with the price list, is already available in your account.

   Create account
2. 2

   Buy a credit package

   Starter (500 credits), Growth (2,500) or Scale (10,000) — pay by card, Pix or boleto in our own checkout. Credits never expire.

   See packages
3. 3

   Create the API key

   Key creation unlocks after the first purchase. The key (msk_live_…) is shown once — copy it into your secrets vault.

   My account
4. 4

   Make the first call

   Send a selfie to POST /api/v1/scan (choosing the models in models) or a photo with shade/color, finish and intensity to POST /api/v1/try-on. The answer arrives in the same request.

curl -X POST https://maiascan.ai/api/v1/scan \
  -H "Authorization: Bearer msk_live_…" \
  -H "x-request-id: order-8841" \
  -F "front=@selfie.jpg;type=image/jpeg" \
  -F "side=@profile.jpg;type=image/jpeg" \
  -F "models=skin,hair_color,hair_type"
# models is optional: omit it for the complete scan, or send e.g. "models=skin"

Authentication

Every route under /api/v1 requires the Authorization header with an API key in Bearer format. The key identifies the account (and therefore the credit balance) and the key itself — usage is recorded per key. Your key never leaves the gateway: calls to the model are made with B4A's credential, on behalf of your account.

Authorization: Bearer msk_live_…

• Format: msk_live_ followed by 32 alphanumeric characters. We store only the SHA-256 hash and a display prefix; the full text is shown once, at creation.
• Up to 10 active keys per account. Revoke any key at any time in the portal (My account → API keys); revocation applies to the next call.
• Missing, invalid or revoked key: 401 with { "error": "invalid_api_key" }.
• Use the key on the server only. Never embed it in browser code or a distributed app — whoever holds the key spends your credits.
• Optional header x-end-user-id (up to 160 characters: letters, digits and @ . _ : + -): your end customer's identifier, forwarded to the model for your own reconciliation. Outside that format it is ignored, never rejected.

Credits

Credits are consumed per operation: a MaIA Scan analysis charges for the models you chose to run (and only those that returned a value), and every image rendered by MaIA Try-On — lipstick or foundation — charges its operation. The credit is reserved before we call the model and settled when the answer arrives; if the model fails, or a scan model cannot predict anything, the corresponding part is refunded automatically. You never pay for a result you did not receive, and we never process a photo we cannot charge.

The current price list (how many credits each operation costs) and the complete technical documentation as a PDF live in the account area, available to any login — even before the first purchase.

Credits never expire. One-off and automatic top-ups follow your last paid package. Enterprise: talk to us.

• The balance after the call comes with every successful response: credits_charged and credits_remaining in the scan JSON and the X-Credits-Charged and X-Credits-Remaining headers on both endpoints.
• Insufficient balance: the call is refused before any processing with 402 and { "error": "insufficient_credits", "balance": 2, "required": 3 }. The attempt is recorded in your usage, without a charge.
• Auto top-up: in the portal you set a threshold and an amount; when the balance drops below it, we create an order and e-mail the payment link (we never charge the card without you).

Browser SDK (early access)

Beyond the photo API, MaIA Try-On exists as a browser SDK: thirteen simulators (lipstick, foundation, blush, powder, concealer, eyeshadow, mascara, eyebrows, eyeliner, bronzer, contour, highlighter and lip liner) and a Full Look, live through the camera or from a photo, rendered locally on the customer's device. No image is uploaded; your brand hosts the immutable bundle on its own origin.

The SDK never calls this API on its own. Lipstick and foundation can get a final server render — through the endpoint above, with the account key server-side — charged in credits like any call; the other products and Full Look are local previews. The integration guide (JavaScript, React, Angular, CSP, privacy, versions) lives in the signed-in area, and access is enabled account by account.

How to get the SDK today

1. Create an account on maiascan.ai (e-mail or Google) and open My account → SDK.
2. Click "Request access": the SDK is in early access and the B4A team enables it account by account. B4A internal teams: ask Jan directly.
3. Once enabled, the same page shows the current version, its SHA-256 and the "Download bundle" button (package.tgz). Host the contents of package/ on your origin at /vendor/maia-try-on/<version>/ — the SDK needs same-origin workers, WASM and models.
4. npm: once enabled, npm i @maiascan/try-on works through our private registry (maiascan.ai/api/npm), authenticated with the account\u2019s API key — the two .npmrc lines are in the signed-in area. No npmjs.com account is needed.

Reference: attribute vocabularies

The possible values of value in result.attributes, per attribute. Vocabularies are fixed per API version (api_version in the model envelope); new values arrive as a compatible change.

Every attribute comes with status predicted, abstained or unsupported; score is an uncalibrated softmax — treat it as a ranking, not as a probability or an accuracy.

Errors and status codes

Every error is JSON with a stable error field (for your code) and a readable message (for the log). Compare error, not message. No error consumes a credit: when the failure happens after the reservation (422 bad_photo or unusable_photo, 429, 503), the refund is written in the same transaction and the body carries session_id.

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": "insufficient_credits",
  "message": "Buy a credit package to continue.",
  "balance": 2,
  "required": 3
}

Limits, idempotency and x-request-id

• Rate limit: 20 requests per minute per API key on every /api/v1 route (429 rate_limited with Retry-After), plus 120 per minute per source IP. For higher volumes, talk to us.
• Idempotency: calls are not idempotent — every 200 consumes credits. Do not automatically retry a call that returned 200; retry only 429 and 503 errors (which do not charge), honouring Retry-After and with exponential backoff.
• x-request-id: send your identifier (up to 80 characters). It is stored on the usage event and shows in reconciliation; use it together with session_id / X-Session-Id and request_id / X-Request-Id when talking to support.
• Timeouts: the gateway waits for the model for up to 180 s. Give your HTTP client at least 200 s so it does not abandon a call that will still be charged and answered.

Data handling and consent

• Consent: you are responsible for obtaining the person's explicit authorisation before sending any photo, under the LGPD. In our own demo the text used is: "I authorise the processing of this photo only to generate the simulation; it is not stored."
• Photos in the gateway: they live in memory only for the duration of the request and are forwarded once to the model. The gateway writes no photos to disk, database or logs — logs record size, operation, latency, status and request identifiers.
• In the MaIA service: nothing is retained or used for training (retained: false, used_for_training: false in the envelope). Only the result — JSON or PNG — comes back to you, with Cache-Control: no-store.
• What we do not do: facial recognition, identification of people, inference of protected traits or medical diagnosis. The analysis is cosmetic and experimental; fields with requires_confirmation must be confirmed with the person.
• Usage log: per request we keep account, key, endpoint, status, credits, latency, x-request-id and the model's request_id — that is what shows on your usage page.

Base URL, version and contact

https://maiascan.ai/api

• Base URL: https://maiascan.ai/api — always HTTPS. Public routes live under /v1.
• Versioning: the version goes in the path (v1). Compatible changes (new JSON fields, new headers, new shades, new vocabulary values) arrive without a version bump; any incompatible change is born as /v2, with /v1 kept in parallel for an announced period.
• Gateway status: GET https://maiascan.ai/api/health returns { "status": "ok", "commit": "…" } — no authentication.
• Technical and commercial support: comercial@b4a.ai.