文件

這是面向產品的公開 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，在不同產品或 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

匿名 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

對於產生的 client 或工具，請使用 /docs/openapi.json.