Documentação

Esta é a referência orientada ao produto para a API pública. A mesma identidade, tenant, versão de estilo, família de avatar, opções de estilo, tamanho e saída WebP devem permanecer estáveis dentro de uma versão major.

Endpoints principais

GET /v1/avatar: returns an avatar asset directly
GET /v1/avatar/link: stores the generated avatar in configured object storage and returns signed-link metadata
GET /avatar/<kind>/<identity>/webp: path-style public avatar URL
GET /docs/openapi.json: machine-readable API description

Endpoints operacionais

GET /healthz é público para load balancers e verificações de disponibilidade. GET /metrics é limitado a loopback e devolve 404 para peers não locais.

Suporte de namespaces

Usa tenant e style_version para manter espaços de identidade visual separados entre produtos ou fases de rollout.

GET https://hashavatar.app/v1/[email protected]&tenant=acme&style_version=v2&algorithm=sha512&kind=wizard&background=white&accessory=hat&color=deep-sea-blue&expression=cool&shape=squircle&format=webp&size=256

IDs anónimos

Envia um id interno estável ou um hash unidirecional da aplicação em vez de dados pessoais em bruto.

printf '%s' '[email protected]' | sha256sum | cut -d' ' -f1

Limites de taxa

O serviço público aplica limites de taxa no origin, com limites mais rigorosos em /v1/avatar/link, pedidos diretos de avatar com persist=true e /og.png porque escritas em armazenamento de objetos e renderização Open Graph são mais caras do que renderização direta.

Timeouts

A geração de avatares e as operações de armazenamento são limitadas por timeouts do servidor para que pedidos caros não monopolizem o origin indefinidamente.

Erros

400: kind inválido, algoritmo ou formato não suportado, tamanho ou identidade em falta
408: timeout de geração ou armazenamento
429: limite de taxa excedido
500: falha de renderização ou armazenamento

OpenAPI

Para clientes gerados ou ferramentas, usa /docs/openapi.json.