API de análisis de piel y prueba virtual de maquillaje — documentación

Visión general

La API MaIA es el gateway HTTPS que B4A expone en maiascan.ai para dos de los tres productos MaIA. Te autenticas con una clave de tu cuenta, envías una foto en multipart/form-data y recibes la respuesta de forma síncrona: un perfil de belleza en JSON (MaIA Scan) o la misma foto en PNG con el producto aplicado (MaIA Try-On). Cada llamada exitosa consume un crédito del saldo de la cuenta.

No se asume nada sobre tu stack: cualquier cliente HTTP capaz de enviar multipart funciona. No hay SDK obligatorio, webhook ni estado de sesión — la respuesta de la llamada es el resultado.

Disponibilidad de los tres productos MaIA
Producto	Disponibilidad	Endpoint	Descripción
MaIA Scan	Autoservicio vía API	`POST /api/v1/scan`	Perfil de piel y cabello en JSON a partir de una selfie frontal (foto de perfil opcional). 1 crédito por análisis.
MaIA Try-On	Autoservicio vía API	`POST /api/v1/try-on`	La foto de la clienta vuelve en PNG con el labial aplicado — en esta versión, los seis tonos y tres acabados de demostración. 1 crédito por render. Paleta calibrada a tus productos: bajo proyecto.
MaIA Beauty Advisor	Bajo proyecto	—	No es un endpoint de autoservicio. B4A lo entrega como proyecto — en el WhatsApp de la marca, como widget en la página de producto o en el chat — usando los mismos datos de perfil que devuelve MaIA Scan y el catálogo integrado de tu marca.

Empieza en cuatro pasos

Crea la cuenta
Entra con Google o recibe un enlace mágico por e-mail. Sin contraseña ni aprobación manual.
Crear cuenta
Compra un paquete de créditos
Starter (500 créditos), Growth (2.500) o Scale (10.000) — tarjeta, Pix o boleto en nuestro propio checkout. Los créditos no expiran.
Ver paquetes
Crea la clave de API
La creación de claves se habilita tras la primera compra. La clave (msk_live_…) se muestra una sola vez — cópiala a tu bóveda de secretos.
Mi cuenta
Haz la primera llamada
Envía una selfie a POST /api/v1/scan o una foto con tono y acabado a POST /api/v1/try-on. La respuesta llega en la misma solicitud.

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"

Autenticación

Toda ruta bajo /api/v1 exige el header Authorization con una clave de API en formato Bearer. La clave identifica la cuenta (y por lo tanto el saldo de créditos) y la propia clave usada — el uso queda registrado por clave.

Authorization: Bearer msk_live_…

Formato: msk_live_ seguido de 32 caracteres alfanuméricos. Guardamos solo el hash SHA-256 y un prefijo de visualización; el texto completo se muestra una única vez, al crearla.
Hasta 10 claves activas por cuenta. Revoca cualquier clave en cualquier momento en el portal (Mi cuenta → Claves de API); la revocación aplica desde la llamada siguiente.
Clave ausente, inválida o revocada: 401 con { "error": "invalid_api_key" }.
Usa la clave solo en el servidor. Nunca la incluyas en código de navegador ni en una app distribuida — quien tenga la clave gasta tus créditos.

Créditos

1 crédito = 1 llamada exitosa, sea un análisis (scan) o un render (try-on). El crédito se reserva antes de llamar al modelo y se liquida cuando llega la respuesta; si el modelo falla, la reserva se devuelve automáticamente — nunca pagas por un resultado que no recibiste, y nunca procesamos una foto que no podemos cobrar.

Paquete	Precio	Créditos	por llamada
Starter	R$ 998	500	R$ 2,00
Growth	R$ 1.998	2.500	R$ 0,80
Scale	R$ 4.998	10.000	R$ 0,50

Las recargas puntuales y automáticas usan el precio por llamada del último paquete pagado. Los créditos no expiran. Enterprise: habla con nosotros.

El saldo tras la llamada viene en toda respuesta exitosa: campo credits_remaining en el JSON del scan y header X-Credits-Remaining en el try-on.
Saldo cero: la llamada se rechaza antes de cualquier procesamiento con 402 y { "error": "insufficient_credits", "balance": 0 }. El intento queda registrado en tu uso, sin cobro.
Recarga automática: en el portal defines un umbral y un monto; cuando el saldo baja de él, creamos un pedido y enviamos el enlace de pago por e-mail (nunca cobramos la tarjeta sin ti).

Ver paquetes y saldo

POST`/api/v1/scan`

Envía una selfie frontal (y opcionalmente una foto de perfil) y recibe el perfil de belleza de la persona en JSON. Síncrono: la respuesta es el resultado.

Estado en producción (22/09/2026): el gateway aún no está conectado al servicio de análisis de la MaIA Scan API. Hasta que se emita la credencial, POST /api/v1/scan responde 503 upstream_not_configured y no se cobra ningún crédito. El contrato de esta sección es el definitivo — integra contra él; la respuesta pasará a ser 200 sin cambios de tu lado.

Solicitud

Cuerpo multipart/form-data con los campos de abajo. Headers: Authorization (obligatorio) y x-request-id (opcional).

Campo	Tipo	Obligatorio	Descripción
`front`	archivo	sí	Foto frontal del rostro. El Content-Type declarado debe ser image/jpeg, image/png, image/webp o image/heic. Hasta 10 MB.
`side`	archivo	opcional	Foto de perfil (lateral) de la misma persona, mismos tipos y límite. Se envía en la misma llamada — sin crédito adicional.
`x-request-id`	header	opcional	Tu identificador de la solicitud (hasta 80 caracteres). Se guarda junto al evento de uso para conciliación; no deduplica llamadas.

Respuesta

200 OK, application/json. El sobre es fijo; result es el documento de análisis devuelto por la MaIA Scan API.

Campo	Tipo	Descripción
`session_id`	string	Identificador del evento de uso (la sesión cobrada). Guárdalo para soporte y conciliación.
`capture_id`	string	Identificador de la captura en la MaIA Scan API.
`credits_remaining`	integer	Saldo de la cuenta tras esta llamada.
`result`	object	Perfil de belleza: tono y subtono de piel, tipo de piel, métricas Skin Scan (enrojecimiento, grasa, textura, poros, manchas, hidratación, pigmentación), color y estructura del cabello, chequeos de calidad de la foto y confianza por campo. Las claves siguen la versión de la MaIA Scan API — trátalo como documento JSON y lee los campos que necesites.

Respuesta

HTTP/1.1 200 OK
Content-Type: application/json

{
  "session_id": "cmg1x3k9h0001abcd",
  "capture_id": "cap_01J8…",
  "credits_remaining": 499,
  "result": { … }
}

Errores

Status	Código	Significado	¿Cobra crédito?
`400`	`front_required`	No se envió el campo front.	no
`400`	`unsupported_media_type`	Content-Type de uno de los archivos fuera de JPEG/PNG/WEBP/HEIC.	no
`401`	`invalid_api_key`	Clave ausente, inválida o revocada.	no
`402`	`insufficient_credits`	Saldo cero; el cuerpo trae balance.	no
`413`	—	Archivo de más de 10 MB (rechazado en la recepción; cuerpo genérico).	no
`429`	—	Más de 120 solicitudes por minuto desde la misma IP.	no
`502`	`analysis_failed`	El modelo no completó el análisis. El crédito reservado fue devuelto; el cuerpo trae session_id.	no
`503`	`upstream_not_configured`	El servicio de análisis no está conectado en este entorno. No se cobra nada.	no

Límites

Hasta 10 MB por archivo, máximo 2 archivos (front + side).
Llamada síncrona; el gateway espera al modelo hasta 60 s.
120 solicitudes por minuto por IP de origen.

Consentimiento obligatorio: obtén la autorización explícita de la persona antes de enviar la foto (LGPD). MaIA Scan no hace reconocimiento facial ni identificación; devuelve análisis cosmético para personalización.

Ejemplos

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"

POST`/api/v1/try-on`

Envía una foto frontal con un tono y un acabado y recibe la misma foto en PNG con el labial aplicado. Solo cambia el área del maquillaje. Síncrono.

Solicitud

Cuerpo multipart/form-data con exactamente los campos de abajo (los campos de texto desconocidos se rechazan con 400). Headers: Authorization (obligatorio) y x-request-id (opcional).

Campo	Tipo	Obligatorio	Descripción
`photo`	archivo	sí	Foto frontal, JPEG o PNG (verificamos los bytes, no el Content-Type). Hasta 6 MB; lado menor de al menos 320 px; boca visible.
`shade`	texto	sí	Uno de los tonos de demostración: rose, red, berry, coral, plum o nude (ver GET /api/v1/try-on/shades).
`finish`	texto	sí	matte, satin o gloss.
`x-request-id`	header	opcional	Tu identificador de la solicitud (hasta 80 caracteres), guardado en el evento de uso.

Respuesta

200 OK, image/png — el cuerpo es la imagen renderizada. El recibo viaja en los headers:

Header	Descripción
`X-Session-Id`	Identificador del evento de uso (la sesión cobrada).
`X-Credits-Remaining`	Saldo de la cuenta tras esta llamada.
`X-TryOn-Finish-Requested`	El acabado que pediste.
`X-TryOn-Finish-Applied`	El acabado efectivamente aplicado. Cuando el modelo no puede aplicar el acabado pedido a una foto, el gateway renderiza en el acabado entrenado del tono (matte para red/berry/plum, satin para rose/coral/nude) en vez de fallar — compara los dos headers para avisar a la persona.
`Cache-Control`	no-store. La imagen no queda en ningún caché de nuestro lado.

Respuesta

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: no-store
X-Session-Id: cmg1x4p2r0002efgh
X-Credits-Remaining: 498
X-TryOn-Finish-Requested: gloss
X-TryOn-Finish-Applied: gloss

<PNG bytes>

Errores

Status	Código	Significado	¿Cobra crédito?
`400`	`photo_required`	No se envió el campo photo.	no
`400`	—	Campo de texto desconocido o mal formado (validación del cuerpo).	no
`401`	`invalid_api_key`	Clave ausente, inválida o revocada.	no
`402`	`insufficient_credits`	Saldo cero; el cuerpo trae balance.	no
`413`	`photo_too_large`	Foto de más de 6 MB. Las subidas muy por encima del límite se cortan en la recepción con un 413 genérico.	no
`422`	`invalid_selection`	shade o finish fuera de la lista.	no
`422`	`unsupported_photo`	Los bytes no son JPEG ni PNG (o el archivo está vacío).	no
`422`	`bad_photo`	El modelo rechazó la foto (rostro no frontal, boca no visible, lado menor por debajo de 320 px). Crédito devuelto.	no
`429`	—	Más de 120 solicitudes por minuto desde la misma IP.	no
`503`	`upstream_unavailable`	El servicio de render falló o está ocupado. Crédito devuelto; reintenta en un momento.	no
`503`	`upstream_not_configured`	El servicio de render no está conectado en este entorno. No se cobra nada.	no

Límites

JPEG o PNG, hasta 6 MB, lado menor ≥ 320 px. Las fotos mayores que 1600 × 1079 px pueden ser reducidas por el modelo antes del render.
Unos 2 a 4 segundos por render. El servicio de render escala a cero: la primera llamada tras un período inactivo puede tardar más (el gateway espera hasta 60 s y reintenta una vez un 422 tardío de cold start).
120 solicitudes por minuto por IP de origen.
El color simulado puede diferir del producto real. En esta versión de la API los tonos son los seis de demostración; la paleta calibrada a los productos de tu marca se entrega bajo proyecto.

Ejemplos

curl -X POST https://maiascan.ai/api/v1/try-on \
  -H "Authorization: Bearer msk_live_…" \
  -F "photo=@selfie.jpg;type=image/jpeg" \
  -F "shade=rose" \
  -F "finish=gloss" \
  -D headers.txt \
  -o try-on.png
# headers.txt now holds X-Session-Id, X-Credits-Remaining, X-TryOn-Finish-Applied

GET`/api/v1/try-on/shades`

Lista los tonos y acabados aceptados por POST /api/v1/try-on, con el hex de referencia y el acabado entrenado de cada tono. No consume crédito.

Respuesta

200 OK, application/json, Cache-Control: private, max-age=3600. Exige la misma clave (401 sin ella).

Campo	Tipo	Descripción
`shades[].id`	string	Valor aceptado en el campo shade del try-on.
`shades[].hex`	string	Color de referencia del tono (#RRGGBB) para mostrar en tu interfaz.
`shades[].trained_finish`	string	Acabado con el que se entrenó el tono — el fallback de X-TryOn-Finish-Applied.
`finishes`	string[]	Valores aceptados en el campo finish.
`max_upload_bytes`	integer	Límite de subida de la foto en bytes (6 MB).

Respuesta

{
  "shades": [
    { "id": "rose",  "hex": "#B85C75", "trained_finish": "satin" },
    { "id": "red",   "hex": "#B8293D", "trained_finish": "matte" },
    { "id": "berry", "hex": "#883252", "trained_finish": "matte" },
    { "id": "coral", "hex": "#D96758", "trained_finish": "satin" },
    { "id": "plum",  "hex": "#703B5B", "trained_finish": "matte" },
    { "id": "nude",  "hex": "#AF786F", "trained_finish": "satin" }
  ],
  "finishes": ["matte", "satin", "gloss"],
  "max_upload_bytes": 6291456
}

Ejemplos

curl https://maiascan.ai/api/v1/try-on/shades \
  -H "Authorization: Bearer msk_live_…"

Errores y códigos de status

Todo error es JSON con un campo error estable (para tu código) y un message legible (para el log). Compara error, no message. Ningún error consume crédito: cuando la falla ocurre después de la reserva (502 en el scan, 422 bad_photo o 503 en el try-on), el crédito se devuelve en la misma transacción.

Status	Significado
`400`	Solicitud mal formada: campo obligatorio ausente, tipo de archivo no declarado correctamente o campo de texto desconocido.
`401`	invalid_api_key — clave ausente, inválida o revocada.
`402`	insufficient_credits — saldo cero; compra un paquete o espera la recarga automática.
`413`	Archivo por encima del límite (10 MB en el scan, 6 MB en el try-on).
`422`	Entrada válida en forma, inválida en contenido: invalid_selection, unsupported_photo, bad_photo (try-on).
`429`	Límite de solicitudes por minuto excedido. Espera y reintenta con backoff.
`502`	analysis_failed — el análisis no se completó; crédito devuelto (scan).
`503`	upstream_unavailable (crédito devuelto) o upstream_not_configured (nada cobrado).

Forma de un error

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

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

Límites, idempotencia y x-request-id

Rate limit: 120 solicitudes por minuto por IP de origen, en todas las rutas /api/v1. Aún no hay límite por clave; para mayores volúmenes, habla con nosotros.
Idempotencia: las llamadas no son idempotentes — cada 200 consume un crédito. No repitas automáticamente una llamada que devolvió 200; reintenta solo 429, 502 y 503 (que no cobran), con backoff exponencial.
x-request-id: envía tu identificador (hasta 80 caracteres). Se guarda en el evento de uso y aparece en la conciliación; cítalo con session_id / X-Session-Id al hablar con soporte.
Timeouts: el gateway espera al modelo hasta 60 s. Configura tu cliente HTTP con al menos 90 s para no abandonar una llamada que igual será cobrada y respondida.

Tratamiento de datos y consentimiento

Consentimiento: eres responsable de obtener la autorización explícita de la persona antes de enviar cualquier foto, según la LGPD. En nuestra propia demo el texto es: "Autorizo el procesamiento de esta foto solo para generar la simulación; no se almacena."
Fotos en el gateway: viven en memoria solo durante la solicitud y se reenvían una vez al modelo. El gateway no escribe fotos en disco, base de datos ni logs — los logs registran tamaño, tono, acabado, latencia y status.
Try-on: la foto no se almacena ni en el gateway ni en el servicio de render; solo el PNG vuelve a ti, con Cache-Control: no-store.
Scan: la MaIA Scan API almacena el resultado estructurado con las versiones de modelo y de pipeline; la retención de la imagen bruta es configurable por proyecto — habla con nosotros para definir la tuya.
Lo que no hacemos: reconocimiento facial, identificación de personas, inferencia de rasgos protegidos ni diagnóstico médico. Los campos de baja confianza deben confirmarse con la persona.
Registro de uso: por llamada guardamos cuenta, clave, endpoint, status, crédito, latencia, x-request-id y, en el scan, el capture_id — es lo que muestra tu página de uso.

Política de Privacidad de B4A →

Base URL, versión y contacto

https://maiascan.ai/api

Base URL: https://maiascan.ai/api — siempre HTTPS. Las rutas públicas viven bajo /v1.
Versionado: la versión va en la ruta (v1). Los cambios compatibles (campos nuevos en el JSON, headers nuevos, tonos nuevos) llegan sin cambio de versión; cualquier cambio incompatible nace como /v2, con /v1 mantenida en paralelo por un período anunciado.
Estado del gateway: GET https://maiascan.ai/api/health devuelve { "status": "ok", "commit": "…" } — sin autenticación.
Soporte técnico y comercial: comercial@b4a.ai.

¿Necesitas más volumen, límites por clave, paleta calibrada a tu catálogo, MaIA Beauty Advisor o un contrato enterprise? Habla con nosotros — B4A entrega proyectos completos sobre la misma API.

Hablar con nosotros Crear cuenta y clave de API

Visión general

Empieza en cuatro pasos

Crea la cuenta

Compra un paquete de créditos

Crea la clave de API

Haz la primera llamada

Autenticación

Créditos

POST/api/v1/scan

Solicitud

Respuesta

Errores

Límites

Ejemplos

POST/api/v1/try-on

Solicitud

Respuesta

Errores

Límites

Ejemplos

GET/api/v1/try-on/shades

Respuesta

Ejemplos

Errores y códigos de status

Límites, idempotencia y x-request-id

Tratamiento de datos y consentimiento

Base URL, versión y contacto

POST`/api/v1/scan`

POST`/api/v1/try-on`

GET`/api/v1/try-on/shades`