API MaIA: análise de pele e cabelo e prova virtual, por HTTP.

Visão geral

A API MaIA é o gateway HTTPS que a B4A expõe em maiascan.ai para dois dos três produtos MaIA. 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) ou a mesma foto em PNG com o produto aplicado (MaIA Try-On). Cada chamada bem-sucedida consome um crédito do saldo da conta.

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.

Comece em quatro passos

1. 1

   Crie a conta

   Entre com Google ou receba um link mágico por e-mail. Não há senha nem aprovação manual.

   Criar conta
2. 2

   Compre um pacote de créditos

   Starter (500 créditos), Growth (2.500) ou Scale (10.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 ou uma foto com tom e acabamento 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"

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.

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.

Créditos

1 crédito = 1 chamada bem-sucedida, seja uma análise (scan) ou um render (try-on). O crédito é reservado antes de chamarmos o modelo e liquidado quando a resposta chega; se o modelo falhar, a reserva é devolvida automaticamente — você nunca paga por um resultado que não recebeu, e nós nunca processamos uma foto que não podemos cobrar.

Recargas avulsas e automáticas usam o preço por chamada do último pacote pago. Créditos não expiram. Enterprise: fale com a gente.

• O saldo após a chamada vem em toda resposta bem-sucedida: campo credits_remaining no JSON do scan e header X-Credits-Remaining no try-on.
• Saldo zero: a chamada é recusada antes de qualquer processamento com 402 e { "error": "insufficient_credits", "balance": 0 }. 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ê).

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 (502 no scan, 422 bad_photo ou 503 no try-on), o crédito é devolvido na mesma transação.

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

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

Limites, idempotência e x-request-id

• Rate limit: 120 requisições por minuto por IP de origem, em todas as rotas /api/v1. Ainda não há limite por chave; para volumes maiores, fale com a gente.
• Idempotência: as chamadas não são idempotentes — cada 200 consome um crédito. Não repita automaticamente uma chamada que devolveu 200; repita apenas erros 429, 502 e 503 (que não cobram), 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 ao falar com o suporte.
• Timeouts: o gateway aguarda o modelo por até 60 s. Configure o seu cliente HTTP com pelo menos 90 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, tom, acabamento, latência e status.
• Try-on: a foto não é armazenada nem pelo gateway nem pelo serviço de render; só o PNG volta para você, com Cache-Control: no-store.
• Scan: a MaIA Scan API armazena o resultado estruturado com as versões de modelo e de pipeline; a retenção da imagem bruta é configurável por projeto — fale com a gente para definir a sua.
• O que não fazemos: reconhecimento facial, identificação de pessoas, inferência de traços protegidos ou diagnóstico médico. Campos com baixa confiança devem ser confirmados com a pessoa.
• Registro de uso: por chamada guardamos conta, chave, endpoint, status, crédito, latência, x-request-id e, no scan, o capture_id — é 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) 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.