「头像生成与获取」接口来自数据鱼API平台,是一个用户头像工具,Base 路径 /api/avatar,共 3 个端点,提供两条互补的能力:按邮箱哈希获取 Gravatar 全球通用头像,以及按用户名生成「首字母头像」的 SVG 图片。前者复用用户在 Gravatar 生态里已有的头像,后者为没有任何头像的用户生成一个确定性的占位图。
首字母头像的生成逻辑是:取名称的第一个字符(多字节安全,中文姓名取第一个汉字),转为大写后居中绘制在纯色背景上。背景色默认由名称的哈希自动推导,同一名称永远得到同一颜色,不同名称大概率得到不同颜色,因此在列表里天然形成稳定的视觉区分;也可以通过参数显式指定背景色与文字颜色。输出为标准的 SVG 文本,尺寸参数化,任意缩放不失真。
Gravatar 端点则是对公共头像服务的一次封装:调用方传入预先算好的哈希值,接口以重定向方式返回头像地址,由客户端直接拉取。两个端点合起来覆盖了「有头像的用户用真实头像、没头像的用户用首字母占位」这一常见的用户列表展示需求,数据鱼API 上它与用户体系类项目搭配使用。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/avatar/ping | 健康检查,返回版本号 | 需要 |
GET | /api/avatar/gravatar | 按哈希重定向到 Gravatar 头像 | 需要 |
GET | /api/avatar/initials | 按名称生成首字母头像 SVG | 需要 |
鉴权使用数据鱼API 全站统一 Key,通过 X-API-Key 请求头或 ?api_key= 查询参数传递;缺失返回 4011,无效返回 4013。initials 与 gravatar 的参数缺失返回 code 4001。需要注意的是,这两个参数错误虽然返回非零 code,HTTP 状态码仍为 200,与全站「参数错误返回 400」的惯例不同。initials 成功时直接返回 image/svg+xml 图片内容而非 JSON。
按名称生成首字母占位头像,返回 SVG 图片。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
name | string | 是 | - | 用户名或姓名,取首字符绘制 |
size | int | 否 | 128 | 画布边长(像素),字号为边长的一半 |
background | string | 否 | 按名称自动取色 | 背景色十六进制值,不带井号 |
color | string | 否 | FFFFFF | 文字颜色十六进制值,不带井号 |
成功时返回 Content-Type: image/svg+xml 的 SVG 文档:正方形画布、纯色背景、居中单字符。name 缺失返回 code 4001。
GET /api/avatar/initials?name=张三&size=64&color=FFFFFF
X-API-Key: YOUR_API_KEY按哈希获取 Gravatar 全球通用头像,接口以 302 重定向返回。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
hash | string | 是 | - | 预先计算好的头像哈希值 |
size | int | 否 | 80 | 请求的图片边长(像素) |
d | string | 否 | mp | 无头像时的兜底样式,如 mp、identicon |
成功响应为 HTTP 302,Location 指向对应的头像地址,客户端(或浏览器)跟随重定向即可拿到图片;hash 缺失返回 code 4001。哈希由调用方自行计算后传入,接口不接收原始邮箱。
GET /api/avatar/gravatar?hash=d41d8cd98f00b204e9800998ecf8427e&size=64&d=identicon
X-API-Key: YOUR_API_KEYbackground 缺省时按名称哈希前六位推导,同名恒同色。d 参数决定兜底样式。code 4001,客户端必须检查业务码而非仅看 HTTP 状态码。color 保证对比度。background 自动取色来自名称哈希,颜色分布不均匀且不可指定色系;对品牌色有要求时显式传参。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。