MaIA API: skin and hair analysis and virtual try-on, over HTTP.

Overview

The MaIA API is the HTTPS gateway B4A exposes at maiascan.ai for two of the three 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 as JSON (MaIA Scan) or the same photo as PNG with the product applied (MaIA Try-On). Every successful call consumes one credit from the account balance.

Nothing is assumed about your stack: any HTTP client that can send multipart works. There is no mandatory SDK, no webhook and no session state — the response of the call is the result.

Start in four steps

1. 1

   Create the account

   Sign in with Google or receive a magic link by e-mail. No password, no manual approval.

   Create account
2. 2

   Buy a credit package

   Starter (500 credits), Growth (2,500) or Scale (10,000) — 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 exactly once — copy it into your secrets vault.

   My account
4. 4

   Make the first call

   Send a selfie to POST /api/v1/scan, or a photo with a shade and a finish to POST /api/v1/try-on. The answer comes back 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"

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.

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 from the next call.
• Missing, invalid or revoked key: 401 with { "error": "invalid_api_key" }.
• Use the key server-side only. Never embed it in browser code or a distributed app — whoever holds the key spends your credits.

Credits

1 credit = 1 successful call, whether an analysis (scan) or a render (try-on). The credit is reserved before we call the model and settled when the answer arrives; if the model fails, the reservation is refunded automatically — you never pay for a result you did not receive, and we never process a photo we cannot charge.

One-off and automatic top-ups use the per-call price of the last paid package. Credits never expire. Enterprise: talk to us.

• The balance after the call comes with every successful response: credits_remaining in the scan JSON and the X-Credits-Remaining header on the try-on.
• Zero balance: the call is refused before any processing with 402 and { "error": "insufficient_credits", "balance": 0 }. The attempt is recorded in your usage, with no 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 a card without you).

Errors and status codes

Every error is JSON with a stable error field (for your code) and a readable message (for your logs). Compare error, not message. No error consumes a credit: when the failure happens after the reservation (502 on scan, 422 bad_photo or 503 on try-on), the credit is refunded in the same transaction.

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

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

Limits, idempotency and x-request-id

• Rate limit: 120 requests per minute per source IP, on every /api/v1 route. There is no per-key limit yet; for higher volumes, talk to us.
• Idempotency: calls are not idempotent — every 200 consumes a credit. Do not automatically repeat a call that returned 200; retry only 429, 502 and 503 (which do not charge), with exponential backoff.
• x-request-id: send your identifier (up to 80 characters). It is stored on the usage event and shows up in reconciliation; quote it with session_id / X-Session-Id when talking to support.
• Timeouts: the gateway waits for the model for up to 60 s. Give your HTTP client at least 90 s so you do 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 authorization before sending any photo, under LGPD. In our own demo the wording is: "I authorize the processing of this photo only to generate the simulation; it is not stored."
• Photos at the gateway: they live in memory for the duration of the request and are forwarded once to the model. The gateway writes photos to no disk, database or log — logs carry size, shade, finish, latency and status.
• Try-on: the photo is stored neither by the gateway nor by the render service; only the PNG comes back to you, with Cache-Control: no-store.
• Scan: the MaIA Scan API stores the structured result with model and pipeline versions; raw-image retention is configurable per project — talk to us to set yours.
• What we do not do: facial recognition, identification of people, inference of protected traits or medical diagnosis. Low-confidence fields should be confirmed with the person.
• Usage record: per call we keep account, key, endpoint, status, credit, latency, x-request-id and, on scan, the capture_id — that is what your usage page shows.

Base URL, versioning and contact

https://maiascan.ai/api

• Base URL: https://maiascan.ai/api — always HTTPS. Public routes live under /v1.
• Versioning: the version is in the path (v1). Compatible changes (new JSON fields, new headers, new shades) ship without a version change; 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.