hashavatar.app
Ayuda Documentación Términos Privacidad Repositorio Crate Rust
Referencia API

Documentación

Esta es la referencia orientada a producto para la API pública. La misma identidad, tenant, versión de estilo, familia de avatar, opciones de estilo, tamaño y salida WebP están pensados para permanecer estables dentro de una versión major.

Endpoints principales

  • 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 operativos

GET /healthz es público para load balancers y comprobaciones de disponibilidad. GET /metrics está limitado a loopback y devuelve 404 para peers no locales.

Soporte de namespaces

Usa tenant y style_version para mantener separados los espacios de identidad visual entre productos o fases de despliegue.

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

Envía un id interno estable o un hash unidireccional de la aplicación en lugar de datos personales sin procesar.

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

Límites de tasa

El servicio público aplica límites de tasa en el origin, con límites más estrictos en /v1/avatar/link, solicitudes directas de avatar con persist=true y /og.png porque las escrituras de almacenamiento de objetos y el renderizado Open Graph son más costosos que el renderizado directo.

Timeouts

La generación de avatares y las operaciones de almacenamiento están acotadas por timeouts del servidor para que las solicitudes costosas no puedan monopolizar el origin indefinidamente.

Errores

  • 400: kind inválido, algoritmo o formato no soportado, tamaño o identidad ausente
  • 408: timeout de generación o almacenamiento
  • 429: límite de tasa excedido
  • 500: fallo de renderizado o almacenamiento

OpenAPI

Para clientes generados o herramientas, usa /docs/openapi.json.