首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >「几何识别头像」接口功能详解|数据鱼API

「几何识别头像」接口功能详解|数据鱼API

原创
作者头像
用户12862874
发布于 2026-11-20 21:58:55
发布于 2026-11-20 21:58:55
190
举报

接口简介

「几何识别头像」是数据鱼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。这一接口没有上游依赖,不会出现第三方服务不可用类的错误。

核心端点详解

生成头像 avatar

按种子生成头像,可调网格密度、单格尺寸与背景色。

参数

类型

必填

默认

说明

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 表示空白,可用于前端自行重绘或做二次加工。

代码语言:javascript
复制
GET /api/identicon/avatar?api_key=YOUR_KEY&seed=alice&blocks=5&size=40&format=json
代码语言:javascript
复制
{
  "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。

健康检查 ping

无请求参数,返回 msg 为 pong,data 含 version、time 与 endpoints 列表。用于探活与确认部署版本,也可在联调初期验证路由与鉴权是否打通。与其他端点一样需要 Key,跨域预检请求除外。

数据与限制

  • 种子长度:最长 128 字符,超出范围按参数非法处理。
  • 网格:blocks 取 3 至 11,默认 5;偶数自动加 1,因此实际网格数只会是奇数。
  • 单格尺寸:size 取 4 至 120 像素,默认 40;画布总边长等于 blocks × size,默认组合为 200 像素。
  • 背景:bg 接受十六进制颜色,缺省为透明;透明背景便于把头像叠在任意底色上。
  • 颜色来源:由种子 MD5 摘要映射到 HSL 色相,同一 seed 的颜色固定,不同 seed 的色相分布均匀。
  • 确定性:相同 seed 与相同参数在任何时刻返回逐字节一致的 SVG,无随机成分。
  • 状态:无状态服务,不落库、不写文件,不保存 seed 与生成结果。
  • 格式:SVG 为矢量输出,缩放不失真;JSON 模式便于同时取得矩阵与颜色元数据。

典型使用场景

社区与后台系统在用户未上传头像时,用用户名或用户 ID 作为种子生成默认头像,保证同一用户每次看到的图案一致。多服务共用同一账号体系时,各端用相同 seed 调用该接口,头像自然统一,无需同步图片文件。评论、协作文档里的参与者标识用邮箱哈希后的种子生成头像,既避免暴露邮箱原文,又能让同一人保持可辨识。前端做主题演示或占位图批量生成时,用 format=json 取回矩阵,再按页面配色重新渲染。

注意事项

blocks 传偶数会被静默加一,调用方若按传入值计算布局,会发现实际画布比预期多一格;应以响应中的 blocks 为准。size 是单格边长而非画布边长,直接把它当成头像尺寸会导致图片偏大或偏小。format 默认为 svg,此时响应不是 JSON,统一按 JSON 解析的客户端会报错;需要元数据时必须显式传 json。

确定性是一把双刃剑。相同 seed 恒定复现,便于缓存,也意味着一旦 seed 泄露或可枚举,他人可以本地复算出同一头像,进而把不同平台上的同一账号关联起来。若在意这一点,应在传参前对原始标识做加盐哈希,再把哈希值作为 seed。MD5 在这里只用于图案派生,不应用于口令存储或完整性校验。

本接口生成的头像仅用于视觉区分,不构成实名认证,也不能证明使用者的真实身份。头像相同不代表账号相同,头像不同也不代表是不同的人。数据鱼API不校验 seed 与任何真实主体的对应关系,涉及账号归属的判断仍需依赖登录凭证与独立的身份核验流程。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 生成头像 avatar
    • 健康检查 ping
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档