API MaIA: análise de pele e cabelo por selfie e simulador de maquiagem, por HTTP.

Visão geral

A API MaIA é o gateway HTTPS que a B4A expõe em maiascan.ai para os produtos MaIA baseados em foto. Você autentica com uma chave da sua conta, envia uma foto em multipart/form-data e recebe a resposta de forma síncrona: um perfil de beleza em JSON (MaIA Scan — tom e subtom de pele, cor e tipo de cabelo, escolhendo quais modelos rodar) ou a mesma foto em PNG com o produto aplicado (MaIA Try-On — batom em tons de demonstração ou em qualquer cor da sua marca, e base como simulador de maquiagem). Os modelos são experimentais: a resposta traz um status por atributo e sinaliza quando a pessoa deve confirmar o resultado.

Nada é assumido do lado da sua stack: qualquer cliente HTTP capaz de enviar multipart funciona. Não há SDK obrigatório, webhook nem estado de sessão — a resposta da chamada é o resultado. A análise é cosmética e baseada em foto: não é diagnóstico, não faz reconhecimento facial e não identifica pessoas.

Preços

Você compra créditos em pacotes — por cartão, Pix ou boleto, no nosso checkout — e usa no scan e na prova virtual. Créditos não expiram. Empresas fora do Brasil pagam em dólar, por cartão: US$ 398, US$ 998 e US$ 4.998.

Recargas avulsas e automáticas seguem o preço por crédito do seu último pacote pago. Volumes enterprise: fale com a gente.

Quantos créditos custa cada operação está na área da conta e na documentação em PDF, disponíveis para qualquer login — antes mesmo da primeira compra.

Comece em quatro passos

1. 1

   Crie a conta

   Entre com Google, e-mail e senha ou receba um link mágico por e-mail. Não há aprovação manual — e a documentação completa em PDF, com a lista de preços, já fica disponível na sua conta.

   Criar conta
2. 2

   Compre um pacote de créditos

   Starter (2.500 créditos), Growth (10.000) ou Scale (60.000) — pagamento por cartão, Pix ou boleto no nosso próprio checkout. Os créditos não expiram.

   Ver pacotes
3. 3

   Crie a chave de API

   A criação de chaves é liberada após a primeira compra. A chave (msk_live_…) aparece uma única vez — copie e guarde no seu cofre de segredos.

   Minha conta
4. 4

   Faça a primeira chamada

   Envie uma selfie para POST /api/v1/scan (escolhendo os modelos em models) ou uma foto com shade/color, finish e intensity para POST /api/v1/try-on. A resposta chega na mesma requisição.

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"

Autenticação

Toda rota em /api/v1 exige o header Authorization com uma chave de API no formato Bearer. A chave identifica a conta (e, portanto, o saldo de créditos) e a própria chave usada — o uso fica registrado por chave. A sua chave nunca sai do gateway: as chamadas ao modelo são feitas com a credencial da B4A, em nome da sua conta.

Authorization: Bearer msk_live_…

• Formato: msk_live_ seguido de 32 caracteres alfanuméricos. Guardamos apenas o hash SHA-256 e um prefixo de exibição; o texto completo é mostrado uma única vez na criação.
• Até 10 chaves ativas por conta. Revogue qualquer chave a qualquer momento no portal (Minha conta → Chaves de API); a revogação vale na chamada seguinte.
• Chave ausente, inválida ou revogada: 401 com { "error": "invalid_api_key" }.
• Use a chave apenas no servidor. Nunca a embuta em código de navegador ou app distribuído — quem tiver a chave gasta os seus créditos.
• Header opcional x-end-user-id (até 160 caracteres: letras, números e @ . _ : + -): o identificador da sua cliente final, repassado ao modelo para a sua própria conciliação. Fora desse formato ele é ignorado, nunca recusado.

Créditos

Os créditos são consumidos por operação: uma análise MaIA Scan cobra pelos modelos que você escolheu rodar (e só pelos que devolveram um valor), e cada imagem renderizada pelo MaIA Try-On — batom ou base — cobra a sua operação. O crédito é reservado antes de chamarmos o modelo e liquidado quando a resposta chega; se o modelo falhar, ou se um modelo do scan não conseguir prever nada, a parte correspondente é devolvida automaticamente. Você nunca paga por um resultado que não recebeu, e nós nunca processamos uma foto que não podemos cobrar.

• O saldo após a chamada vem em toda resposta bem-sucedida: campos credits_charged e credits_remaining no JSON do scan e headers X-Credits-Charged e X-Credits-Remaining em ambos os endpoints.
• Saldo insuficiente: a chamada é recusada antes de qualquer processamento com 402 e { "error": "insufficient_credits", "balance": 2, "required": 3 }. A tentativa fica registrada no seu uso, sem cobrança.
• Recarga automática: no portal você define um limiar e um valor; quando o saldo cai abaixo dele, criamos um pedido e enviamos o link de pagamento por e-mail (nunca cobramos o cartão sem você).

SDK no navegador (acesso antecipado)

Além da API por foto, o MaIA Try-On existe como um SDK para o navegador: treze simuladores (batom, base, blush, pó, corretivo, sombra, máscara, sobrancelhas, delineador, bronzer, contorno, iluminador e lápis de boca) e o Full Look, ao vivo pela câmera ou em foto, renderizados localmente no aparelho da cliente. Nenhuma imagem é enviada; a sua marca hospeda o pacote imutável na própria origem.

O SDK nunca chama esta API por conta própria. Batom e base podem receber um render final no servidor — pelo endpoint acima, com a chave da conta do lado do servidor — cobrado em créditos, como qualquer chamada; os demais produtos e o Full Look são prévias locais. O guia de integração (JavaScript, React, Angular, CSP, privacidade, versões) fica na área logada, e o acesso é liberado conta a conta.

Como obter o SDK hoje

1. Crie uma conta em maiascan.ai (e-mail ou Google) e entre em Minha conta → SDK.
2. Clique em "Pedir acesso": o SDK está em acesso antecipado e a equipe B4A libera conta a conta.
3. Com o acesso liberado, a mesma página mostra a versão atual, o SHA-256 e o botão "Baixar pacote" (package.tgz). Hospede o conteúdo de package/ na sua origem em /vendor/maia-try-on/<versão>/ — o SDK exige mesma origem para workers, WASM e modelos.
4. npm: com o acesso liberado, npm i @maiascan/try-on funciona pelo nosso registro privado (maiascan.ai/api/npm), autenticado com a chave de API da conta — as duas linhas do .npmrc estão na área logada. Nenhuma conta no npmjs.com é necessária.

Referência: vocabulários dos atributos

Os valores possíveis de value em result.attributes, por atributo. Os vocabulários são fixos por versão da API (api_version no envelope do modelo); valores novos chegam como mudança compatível.

Cada atributo vem com status predicted, abstained ou unsupported; score é um softmax não calibrado — trate como ordem de preferência, não como probabilidade nem acurácia.

Erros e códigos de status

Todo erro é JSON com um campo error estável (para o seu código) e message legível (para o log). Compare error, não message. Nenhum erro consome crédito: quando a falha acontece depois da reserva (422 bad_photo ou unusable_photo, 429, 503), a devolução é gravada na mesma transação e o corpo traz 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
}

Limites, idempotência e x-request-id

• Rate limit: 20 requisições por minuto por chave de API em todas as rotas /api/v1 (429 rate_limited com Retry-After), além de 120 por minuto por IP de origem. Para volumes maiores, fale com a gente.
• Idempotência: as chamadas não são idempotentes — cada 200 consome créditos. Não repita automaticamente uma chamada que devolveu 200; repita apenas erros 429 e 503 (que não cobram), respeitando Retry-After e com backoff exponencial.
• x-request-id: envie o seu identificador (até 80 caracteres). Ele é gravado no evento de uso e aparece na conciliação; use-o com session_id / X-Session-Id e request_id / X-Request-Id ao falar com o suporte.
• Timeouts: o gateway aguarda o modelo por até 180 s. Configure o seu cliente HTTP com pelo menos 200 s para não abandonar uma chamada que ainda será cobrada e respondida.

Tratamento de dados e consentimento

• Consentimento: você é responsável por obter a autorização explícita da pessoa antes de enviar qualquer foto, nos termos da LGPD. Na nossa própria demo o texto usado é: "Autorizo o processamento desta foto apenas para gerar a simulação; ela não é armazenada."
• Fotos no gateway: ficam em memória apenas durante a requisição e são encaminhadas uma vez ao modelo. O gateway não grava fotos em disco, banco ou logs — os logs registram tamanho, operação, latência, status e identificadores de requisição.
• No serviço MaIA: nada é retido nem usado para treino (retained: false, used_for_training: false no envelope). Só o resultado — JSON ou PNG — volta para você, com Cache-Control: no-store.
• O que não fazemos: reconhecimento facial, identificação de pessoas, inferência de traços protegidos ou diagnóstico médico. A análise é cosmética e experimental; campos com requires_confirmation devem ser confirmados com a pessoa.
• Registro de uso: por requisição guardamos conta, chave, endpoint, status, créditos, latência, x-request-id e o request_id do modelo — é o que aparece na sua página de uso.

Base URL, versão e contato

https://maiascan.ai/api

• Base URL: https://maiascan.ai/api — sempre HTTPS. As rotas públicas ficam sob /v1.
• Versionamento: a versão vai no caminho (v1). Mudanças compatíveis (campos novos no JSON, headers novos, tons novos, valores novos nos vocabulários) chegam sem troca de versão; qualquer mudança incompatível nasce como /v2, com /v1 mantida em paralelo por um período anunciado.
• Status do gateway: GET https://maiascan.ai/api/health devolve { "status": "ok", "commit": "…" } — sem autenticação.
• Suporte técnico e comercial: comercial@b4a.ai.