Docs
文档目录

头像与图形

这是什么 / 何时用

Avatars 服务提供开箱即用的图片与图标动态渲染能力,包括:姓名/文本首字母头像生成(getInitials)、二维码图片生成(getQR)、国家与地区国旗图标(getFlag)、主流浏览器图标(getBrowser)以及国际卡组织/支付品牌图标(getCreditCard)。此外,接口契约中还包含远程图片裁剪(getImage)、站点 Favicon 提取(getFavicon)与网页截图(getScreenshot)三个远程抓取入口(受 2.6.0+ SSRF 安全基线默认关闭约束)。

在企业智能客服与知识中台(如演示项目 enterprise-ai-hub-210)中,客户端与服务端可通过 Avatars 为未上传自定义头像的客服人员与访客(如 user_zhangwei_001、user_lina_002)实时生成统一视觉规范的首字母头像,为工单分享链接或移动端扫码登录生成 PNG 二维码,或在会话审计列表中展示访客来源国家国旗与浏览器图标。

前置

使用骨架

  1. 初始化 Client 与 Avatars 服务:装载项目 ID 与鉴权凭据,构造 new Avatars(client)。

  2. 生成首字母头像(getInitials):传入用户姓名 name(省略时取当前登录用户名,无会话时回退为空格)、目标宽高(width / height,0–2000 像素)与十六进制背景色(background,不含 # 号,如 0969da)。

  3. 生成二维码(getQR):传入待编码文本 text(1–1024 字符,如工单链接或一次性登录令牌)、尺寸 size(1–1000 像素)、白边宽度 margin(0–10)及是否触发附件下载 download。

  4. 获取标准图标(getFlag / getBrowser / getCreditCard):传入对应的标准枚举码 code(如国旗 ISO 3166-1 Alpha-2 cn、浏览器 ch / sf / ff、卡组织 visa / mastercard / unionpay)及可选 width、height、quality(0–100)。

  5. 处理二进制图片响应:所有 Avatars 方法均直接返回原始图片字节流(ArrayBuffer / byte[] / bytes),服务端可直接写入文件、上传至 Storage 桶或设置 Content-Type: image/png 转发给前端。

关键参数与返回

方法全集与参数矩阵

SDK 方法(Node / Web / Java)Python 方法Go 方法REST 端点关键参数说明
getInitials({ name, width, height, background })(name、width、height、background 均可选)get_initials(...)GetInitials(...)GET /v1/avatars/initialsname(≤128 字符)、width(0–2000,默认 500)、height(0–2000,默认 500)、background(6 位 Hex,如 0969da)生成姓名首字母头像 PNG 字节。
getQR({ text, size, margin, download })(size、margin、download 均可选)get_qr(...)GetQR(...)GET /v1/avatars/qrtext(必填)、size(1–1000,默认 400)、margin(0–10,默认 1)、download(boolean,默认 false)将文本或 URL 渲染为二维码图片。
getFlag({ code, width, height, quality })(width、height、quality 均可选)get_flag(...)GetFlag(...)GET /v1/avatars/flags/{code}code(必填,ISO Alpha-2 小写枚举如 cn、us、jp)、width(0–2000)、height(0–2000)、quality(0–100)获取国家/地区国旗图片。
getBrowser({ code, width, height, quality })(width、height、quality 均可选)get_browser(...)GetBrowser(...)GET /v1/avatars/browsers/{code}code(必填,枚举如 ch Chrome、ff Firefox、sf Safari、ed Edge)、width、height、quality获取浏览器品牌图标。
getCreditCard({ code, width, height, quality })(width、height、quality 均可选)get_credit_card(...)GetCreditCard(...)GET /v1/avatars/credit-cards/{code}code(必填,枚举如 visa、mastercard、amex、unionpay、jcb)、width、height、quality获取卡组织/支付方式图标。
getImage({ url, width, height })(width、height 均可选)get_image(...)GetImage(...)GET /v1/avatars/imageurl(远程图片 URL)、width、height2.6.0+ 默认关闭(SSRF 安全默认)。
getFavicon({ url })get_favicon(...)GetFavicon(...)GET /v1/avatars/faviconurl(远程站点 URL)2.6.0+ 默认关闭(SSRF 安全默认)。
getScreenshot({ url, ... })get_screenshot(...)GetScreenshot(...)GET /v1/avatars/screenshotsurl(远程网页 URL)及视口/主题参数2.6.0+ 默认关闭(SSRF 安全默认)。

返回值结构

错误与边界

SDK 类别差异

SDK 类别支持范围鉴权方式典型场景
Server SDK(Node.js / Java / Python / Go)全量方法(返回图片二进制字节流)项目 API Key(avatars.read)后端批量生成用户默认头像并归档至 Storage、生成工单二维码邮件附件
Client / Web SDK(Web)全量方法用户 Session(或公开项目标识)前端渲染用户姓名首字母头像、扫码登录二维码、国旗与浏览器徽标
Console SDK(Node.js / Java / Python / Go)全量方法管理面 Session / 短期 JWT控制台成员列表头像、会话审计端浏览器/国旗图标展示

各语言调用示例

客户端与服务端均可用;Web 页签走用户 Session。远程 Image / Favicon / Screenshot 默认不可用(2.6.0 安全默认值,见「错误与边界」)。

import { Client, Avatars, AgentbaseException } from 'agentbase-node-sdk';
import { writeFileSync } from 'node:fs';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
    .setProject(process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210')
    .setKey(process.env.APPBASE_API_KEY!);

const avatars = new Avatars(client);

try {
    // 1. 生成文字头像(可设宽高与 6 位十六进制背景色,不含 #)
    const initialsBuf = await avatars.getInitials({
        name: 'Zhang Wei',
        width: 256,
        height: 256,
        background: '0969da',
    });
    writeFileSync('/tmp/avatar-zhangwei.png', Buffer.from(initialsBuf));

    // 2. 生成工单分享二维码与国旗图标
    const qrBuf = await avatars.getQR({
        text: 'https://appbuild-sit.oceanbase.com/tickets/TK-20261022-001',
        size: 320,
        margin: 2,
    });
    const flagBuf = await avatars.getFlag({ code: 'cn', width: 64, height: 48 });
    console.log('生成成功,二维码字节:', qrBuf.byteLength, '国旗字节:', flagBuf.byteLength);
    // 2.6.0 安全默认值:远程 getImage / getFavicon / getScreenshot 默认不可用(SSRF 防护收紧),不是故障
} catch (err) {
    if (err instanceof AgentbaseException) {
        console.error(`Avatars 调用失败 [${err.code} ${err.type}]: ${err.message}`);
    }
    throw err;
}

示例指引