「几何识别头像」是数据鱼API平台提供的确定性头像生成接口,Base 路径 /api/identicon,共 2 个端点:健康检查与头像生成。它接收一个字符串种子,输出一张左右对称的几何图案头像,风格接近代码托管平台常见的 identicon:同一种子永远得到同一张图,不同种子得到颜色与方块分布不同的图。
生成过程完全由种子决定。服务端对种子计算 MD5,从摘要中取出颜色与图案参数,再按网格逐格绘制矩形,随后把左半部分镜像到右半部分形成对称结构。输出是纯 SVG 文本,不依赖 GD 等图像扩展,因此体积极小、可无损缩放,也能直接嵌入网页作为内联图形。
这一接口适合给还没有上传头像的账号提供占位图,或用昵称、邮箱、用户 ID 派生一个稳定可辨识的视觉标识。数据鱼API在这一接口上不保存任何生成结果,同一请求重复调用返回完全一致的 SVG,便于配合 CDN 或浏览器缓存。需要强调的是,头像只是视觉层面的区分手段,不承载身份认证能力。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/identicon/ping | 健康检查,返回版本与可用端点 | 是(跨域预检除外) |
GET | /api/identicon/avatar | 由 seed 生成对称几何头像 | 是 |
鉴权使用全站统一 Key,通过 X-API-Key 请求头或 ?api_key= 查询参数传递,缺失返回 4011,无效返回 4013。除跨域预检的 OPTIONS 外,所有端点都需要鉴权。标注为 GET 的端点同样接受 POST,参数名一致,可用 JSON body 或表单提交。
响应有两种形态:format=svg(默认)时直接返回图片内容,Content-Type 为 SVG;format=json 时返回统一的三段式 JSON,把 SVG 文本放在 data.svg 中。错误响应始终是 JSON,缺少参数返回 4001,参数非法返回 4002,路由不存在返回 4040,服务内部异常返回 5000。这一接口没有上游依赖,不会出现第三方服务不可用类的错误。
按种子生成头像,可调网格密度、单格尺寸与背景色。
参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
seed | string | 是 | — | 头像种子,通常传用户名、邮箱或用户 ID,最长 128 字符 |
blocks | int | 否 | 5 | 网格边长方块数,取值 3 至 11;传偶数时自动加 1 以保持左右对称 |
size | int | 否 | 40 | 单个方块的像素边长,取值 4 至 120 |
bg | string | 否 | 透明 | 背景色,十六进制写法如 #aabbcc;不传则背景透明 |
format | string | 否 | svg | svg 直接返回图片,json 返回带元数据的 JSON |
返回 JSON 时,data 包含六个字段:svg 为完整图形文本;size 为画布总边长,等于网格数乘以单格边长;blocks 为实际采用的网格数(偶数已加一);color 为主色,采用 HSL 写法;bg 为背景色,透明时为 transparent;matrix 是二维数组形式的图案矩阵,1 表示着色方块,0 表示空白,可用于前端自行重绘或做二次加工。
GET /api/identicon/avatar?api_key=YOUR_KEY&seed=alice&blocks=5&size=40&format=json{
"code": 0,
"msg": "success",
"data": {
"svg": "<svg width=\"200\" height=\"200\" viewBox=\"0 0 200 200\">...</svg>",
"size": 200,
"blocks": 5,
"color": "hsl(33, 65%, 50%)",
"bg": "transparent",
"matrix": [[1,0,0,0,1],[0,1,0,1,0],[1,1,1,1,1],[0,0,1,0,0],[0,1,1,1,0]]
}
}matrix 的每一行左右对称,第一行首尾同值、第二行次列对称,中间列可以任意。这一结构是生成算法直接产出的,调用方若需要在前端把头像渲染成 Canvas 或 CSS 网格,可以直接消费矩阵而不必解析 SVG。
无请求参数,返回 msg 为 pong,data 含 version、time 与 endpoints 列表。用于探活与确认部署版本,也可在联调初期验证路由与鉴权是否打通。与其他端点一样需要 Key,跨域预检请求除外。
blocks 取 3 至 11,默认 5;偶数自动加 1,因此实际网格数只会是奇数。size 取 4 至 120 像素,默认 40;画布总边长等于 blocks × size,默认组合为 200 像素。bg 接受十六进制颜色,缺省为透明;透明背景便于把头像叠在任意底色上。社区与后台系统在用户未上传头像时,用用户名或用户 ID 作为种子生成默认头像,保证同一用户每次看到的图案一致。多服务共用同一账号体系时,各端用相同 seed 调用该接口,头像自然统一,无需同步图片文件。评论、协作文档里的参与者标识用邮箱哈希后的种子生成头像,既避免暴露邮箱原文,又能让同一人保持可辨识。前端做主题演示或占位图批量生成时,用 format=json 取回矩阵,再按页面配色重新渲染。
blocks 传偶数会被静默加一,调用方若按传入值计算布局,会发现实际画布比预期多一格;应以响应中的 blocks 为准。size 是单格边长而非画布边长,直接把它当成头像尺寸会导致图片偏大或偏小。format 默认为 svg,此时响应不是 JSON,统一按 JSON 解析的客户端会报错;需要元数据时必须显式传 json。
确定性是一把双刃剑。相同 seed 恒定复现,便于缓存,也意味着一旦 seed 泄露或可枚举,他人可以本地复算出同一头像,进而把不同平台上的同一账号关联起来。若在意这一点,应在传参前对原始标识做加盐哈希,再把哈希值作为 seed。MD5 在这里只用于图案派生,不应用于口令存储或完整性校验。
本接口生成的头像仅用于视觉区分,不构成实名认证,也不能证明使用者的真实身份。头像相同不代表账号相同,头像不同也不代表是不同的人。数据鱼API不校验 seed 与任何真实主体的对应关系,涉及账号归属的判断仍需依赖登录凭证与独立的身份核验流程。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。