Referência

API v1

Base URL: https://api.nutoken.com.br/v1 · Autenticação: Authorization: Bearer <chave> · Corpo: multipart/form-data (criação com imagem) ou application/json.

Análises

POST/v1/analyses

Cria uma análise a partir de uma imagem. Responde 202 com analysis_id, ou 422 imediato para erros de validação detectáveis na entrada.

Campo	Tipo	Obrigatório	Descrição
`image`	file	sim*	JPEG/PNG/WebP/HEIC ≤ 10 MB (*ou `upload_id`)
`upload_id`	string	—	Alternativa para arquivos grandes (ver `POST /v1/uploads`)
`dimensions`	array JSON	sim	Dimensões a analisar (lista)
`consent`	objeto JSON	sim	`{obtained, policy_version, subject_ref, purposes?}`
`webhook_url`	string	—	Sobrepõe o endpoint configurado no painel
`masks`	string	—	`per_region` (default) · `composite` · `none`
`chronological_age`	int	—	Habilita `skin_age.chronological_delta`
`locale` · `metadata`	—	—	Idioma dos rótulos · até 10 pares seus

Headers: Idempotency-Key (fortemente recomendado; guardado por 24 h).

GET/v1/analyses/{analysis_id}

Status e resultado. status: processing · succeeded · failed. Resultado completo disponível por 72 h; depois, metadados.

GET/v1/analyses?subject_ref=u_84f2&limit=20

Lista análises (paginação por cursor: starting_after). Filtros: subject_ref, status, created_after. Essencial para séries temporais de evolução.

POST/v1/analyses/{analysis_id}/masks

Reemite URLs assinadas de máscaras expiradas (0,1 unidade).

Uploads (opcional, para arquivos grandes)

POST/v1/uploads

Body: {"content_type":"image/jpeg","file_size":12582912} → responde upload_id + put_url assinada (15 min). Faça PUT do binário e use upload_id na criação da análise.

Titulares e consentimento

GET/v1/subjects/{subject_ref}

Resumo do titular: análises, consentimentos registrados e retenções ativas.

DELETE/v1/subjects/{subject_ref}

Apaga dados do titular (direito de eliminação LGPD). Responde 202 com deletion_id; conclusão confirmada via webhook. Dados sob obrigação legal de retenção do controlador não são afetados — a resposta discrimina o que foi removido.

Unidades e webhooks

GET/v1/units

Saldo, lotes e expirações. Ver Unidades & cobrança.

POST/v1/webhooks/test

Dispara evento de teste no sandbox. Ver Webhooks.

Códigos de status

HTTP	Quando
`202`	Análise aceita (processando)
`200`	Consulta bem-sucedida
`400 / 422`	Requisição ou conteúdo inválido (catálogo)
`401 / 402 / 409`	Chave inválida · sem unidades · conflito de idempotência
`429`	Rate limit — veja `Retry-After`. Limites padrão: 10 análises/s, 60 GETs/s por chave (ajustável por contrato)
`5xx`	Erro nosso — retry com backoff é seguro graças à idempotência

Versionamento e depreciação

Versão no caminho (/v1/). Mudanças aditivas (novos campos/dimensões) acontecem dentro da v1 — escreva parsers tolerantes a campos novos.
Mudanças incompatíveis criam /v2/, com a v1 mantida por no mínimo 12 meses após o anúncio, com cronograma público.
Toda resposta traz model_version: scores são comparáveis dentro da mesma versão de modelo; o changelog de modelos documenta cada recalibração e a função de conversão, quando houver.