文档

这是面向产品的公开 API 参考。相同的身份标识、tenant、样式版本、头像家族、样式选项、尺寸和 WebP 输出应在同一 major 版本内保持稳定。

核心端点

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

运维端点

GET /healthz 面向负载均衡器和可用性检查公开。GET /metrics 仅限 loopback，并对非本地 peer 返回 404。

Namespace 支持

使用 tenant 和 style_version 在不同产品或发布阶段之间分隔视觉身份空间。

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

匿名 ID

请发送稳定的内部 ID 或应用侧单向哈希，而不是原始个人数据。

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

速率限制

公开服务在 origin 侧应用速率限制。由于对象存储写入和 Open Graph 图片渲染比直接渲染更昂贵，/v1/avatar/link、带 persist=true 的直接头像请求以及 /og.png 会使用更严格的限制。

超时

头像生成和存储操作受服务器端超时限制，避免昂贵请求无限期占用 origin。

错误

400: kind 无效、算法或格式不支持、尺寸无效或缺少身份标识
408: 生成或存储超时
429: 超过速率限制
500: 渲染或存储失败

OpenAPI

对于生成客户端或工具，请使用 /docs/openapi.json.