Entradas & saídas
O que a API aceita, o que ela devolve, e o significado exato de cada campo — sem caixas-pretas.
Dimensões de pele (dimensions)
Peça só o que vai usar — a resposta fica menor e o processamento, mais rápido. As 8 dimensões núcleo:
| Valor | Analisa | Regiões reportadas |
|---|---|---|
wrinkle | Rugas e linhas | fronte, glabela, periocular, nasogeniano, marionete |
pore | Poros visíveis | fronte, nariz, bochechas |
texture | Uniformidade e microtextura | face inteira + zonas |
acne | Lesões ativas e marcas | zonas acometidas |
oiliness | Oleosidade aparente | zona T, bochechas |
moisture | Hidratação estimada | face inteira |
redness | Vermelhidão/eritema | bochechas, nariz, mento |
age_spot | Manchas e hiperpigmentação | zonas acometidas |
Dimensões estendidas (EM BREVE): radiance, dark_circle, eye_bag, firmness, tear_trough, skin_type. Diferente do mercado, não há famílias "SD" e "HD" incompatíveis entre si: a resolução de entrada define automaticamente a fidelidade da análise, e as dimensões são as mesmas.
O objeto consent (obrigatório)
Foto facial é dado biométrico sensível. A API não processa sem a declaração de consentimento do titular, que fica registrada para auditoria — sua e nossa:
{
"obtained": true, // você coletou consentimento explícito
"policy_version": "2026-10", // versão do seu termo aceito pelo titular
"subject_ref": "u_84f2", // SEU identificador pseudonimizado do titular
"purposes": ["analysis"] // opcional: ["analysis","model_improvement"]
}DELETE /v1/subjects/{subject_ref}.Parâmetros opcionais
| Campo | Default | Efeito |
|---|---|---|
webhook_url | endpoint do painel | Para onde enviar analysis.completed |
masks | "per_region" | "per_region" (uma URL por achado), "composite" (uma imagem com tudo sobreposto) ou "none" |
locale | "pt-BR" | Idioma dos rótulos legíveis (pt-BR, en-US, es-419) |
metadata | — | Até 10 pares chave-valor seus, devolvidos intactos na resposta e no webhook |
Anatomia da resposta
dimensions[] — um objeto por dimensão
| Campo | Significado |
|---|---|
score | 0–100, maior = pele com menos sinais da condição. Valor técnico: estável, comparável entre análises do mesmo titular e documentado por versão de modelo. |
display_score | Variante calibrada para exibição ao consumidor. A calibração é pública: compressão suave da metade inferior da escala (função monotônica publicada no changelog do modelo) — nunca reordena resultados nem inverte tendências. Use score para lógica e séries temporais; display_score para UI, se quiser. |
confidence | 0–1. Abaixo de 0,70, trate como resultado parcial (foto no limite de qualidade). |
regions[] | Achados localizados: area (ex.: cheek_left), severity (minimal·mild·moderate·marked) e mask_url. |
skin_age
Idade estimada da pele em anos (years) e, quando a idade cronológica for informada, o delta (chronological_delta). É uma estimativa de modelo relativa à distribuição populacional da nossa base consentida — a resposta diz isso em safety.disclaimer, e a sua UI deve dizer também.
safety
Se o motor detectar um padrão que mereça avaliação profissional (ex.: lesão com características atípicas), safety.flags conterá professional_review_recommended — sem nomear hipóteses clínicas. Sua aplicação deve exibir a recomendação ao usuário. Isto é parte dos nossos limites não diagnósticos e não é configurável.
Máscaras (mask_url)
PNGs com transparência, alinhados pixel a pixel à imagem enviada (após o auto-resize), entregues como URLs assinadas válidas por 72 h. Sobreponha com <canvas> ou CSS — sem ZIP para baixar, descompactar e hospedar.