ドキュメント

これは公開APIのプロダクト向けリファレンスです。同じ識別子、tenant、スタイルバージョン、アバターファミリー、スタイルオプション、サイズ、WebP出力は、同じメジャーバージョン内で安定することを意図しています。

主要エンドポイント

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.