#头像接口

一个免费的接口，能把任意字符串变成一个角色。把地址放进 <img>，就得到一个确定的 Aora Bot 头像：同一个 id 永远返回同一个角色，不用安装、不用存储、也不用注册。

#使用

<img src="https://aora-bot.vercel.app/avatar/alice.svg" width="64" height="64" alt="alice" />

在 Markdown 里同样可用，适合 README、issue 或任何允许外链图片的评论区：

![alice](https://aora-bot.vercel.app/avatar/alice.svg)

id 可以是任意不超过 128 个字符的 URL 安全字符串：用户名、邮箱哈希、数据库主键都行。.svg 后缀可以省略。

#参数

所有参数都是可选的，写在查询字符串里。

各画风的变体：

• vector：solid（默认）、outline、glass、sticker、paper、soft、riso
• pixel：crisp（默认）、dot、block
• kaomoji：plain（默认）、bubble

所选画风的每个参数也都可以作为查询参数，例如 vector 的 strokeWidth 或 paperOffset，pixel 的 grid 或 outline，kaomoji 的 weight 或 tail。数字直接写数字，布尔值写 true 或 false（也接受 1 和 0）。取值范围见各画风页面：vector、pixel、kaomoji。

https://aora-bot.vercel.app/avatar/alice.svg?style=pixel&variant=block&size=96
https://aora-bot.vercel.app/avatar/alice.svg?state=happy
https://aora-bot.vercel.app/avatar/mochi-blue.svg?shape=mochi&color=blue&state=happy
https://aora-bot.vercel.app/avatar/alice.svg?variant=paper&paperOffset=12

首页的控制台可以替你生成这样的地址：在代码条上选择头像格式，就能复制你搭好的角色的链接。

取值不在上述范围内，例如 style=oil、color=plaid、size=big，或超出范围的画风参数，会返回 HTTP 400 和一行纯文本原因。接口不认识的查询参数会被忽略。背景是透明的。

#你会得到哪个角色

如果 id 恰好是阵容里的角色 id，就得到那个角色：/avatar/luna.svg 就是露娜。其他 id 会被哈希到 46 位阵容成员中的一位，结果稳定，分布也均匀。shape、color 和 face 会替换由 id 选出的内容，所以三者都写上时，id 只是一个文件名。阵容只有 46 位，所以不同的 id 可能落到同一个角色上；请把它当作一个友好的默认头像，而不是唯一的身份标识。

对同一个引擎版本，结果是固定的。如果某次发布重画了角色或调整了阵容，同一个 id 的样子可能随之改变。

#缓存与嵌入

响应的类型是 image/svg+xml，Cache-Control 为 public, max-age=86400, s-maxage=31536000, stale-while-revalidate=604800：浏览器缓存一天，边缘节点缓存一年。接口带有 Access-Control-Allow-Origin: *，所以也可以在任意来源下用 fetch 获取。SVG 是独立的：没有脚本，也没有外部引用。

放在 <img> 里时，SVG 看不到你的页面，因此部分角色的墨色会跟随访客的系统浅色或深色设置，而不是你网站的主题。

#在应用里，请在本地渲染

做产品时，建议自己渲染头像，而不是每次浏览页面都请求一次接口。服务端安全的入口不需要 DOM，也不需要网络：

import { castMember, renderStaticSvg } from '@aora-bot/engine/static';

const luna = castMember('luna')!;
const svg = renderStaticSvg({ shape: luna.shape, color: luna.color, state: 'happy', sizePx: 64 });

renderAvatarDataUrl(key) 能用一行代码为任意 key 做同样的事。它从引擎自己的候选池里挑选，所以同一个 id 得到的角色与这个接口挑出的并不相同。更多细节见服务端渲染。