头像与图形
运行示例前,将 <APPBASE_ENDPOINT_WITH_V1> 替换为目标环境的 API 地址,并核对项目及凭据属于同一环境。
这是什么 / 何时用
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 二维码,或在会话审计列表中展示访客来源国家国旗与浏览器图标。
前置
客户端初始化与认证:
Server SDK(Node.js / Java / Python / Go):通过
setEndpoint('https://appbuild-sit.oceanbase.com/v1')、setProject('enterprise-ai-hub-210')、setKey('<APPBASE_API_KEY>')初始化,API Key 需具备avatars.readscope。Client / Web SDK:通过
setEndpoint、setProject初始化(可配合用户 Session 使用)。Console SDK:支持管理面 Session 或短期 JWT。
2.6.0+ 安全默认值(SSRF 防护):远程 Avatar Image(
getImage)、Favicon(getFavicon)、Screenshot(getScreenshot)默认不可用(外部 URL 拒绝本机/私网/云元数据地址的 SSRF 防护默认收紧)——不要在生产环境建议长期关闭 SSRF 防护来恢复旧行为。
使用骨架
初始化
Client与Avatars服务:装载项目 ID 与鉴权凭据,构造new Avatars(client)。生成首字母头像(
getInitials):传入用户姓名name(省略时取当前登录用户名,无会话时回退为空格)、目标宽高(width/height,0–2000 像素)与十六进制背景色(background,不含#号,如0969da)。生成二维码(
getQR):传入待编码文本text(1–1024 字符,如工单链接或一次性登录令牌)、尺寸size(1–1000 像素)、白边宽度margin(0–10)及是否触发附件下载download。获取标准图标(
getFlag/getBrowser/getCreditCard):传入对应的标准枚举码code(如国旗 ISO 3166-1 Alpha-2cn、浏览器ch/sf/ff、卡组织visa/mastercard/unionpay)及可选width、height、quality(0–100)。处理二进制图片响应:所有
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/initials | name(≤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/qr | text(必填)、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/image | url(远程图片 URL)、width、height | 2.6.0+ 默认关闭(SSRF 安全默认)。 |
getFavicon({ url }) | get_favicon(...) | GetFavicon(...) | GET /v1/avatars/favicon | url(远程站点 URL) | 2.6.0+ 默认关闭(SSRF 安全默认)。 |
getScreenshot({ url, ... }) | get_screenshot(...) | GetScreenshot(...) | GET /v1/avatars/screenshots | url(远程网页 URL)及视口/主题参数 | 2.6.0+ 默认关闭(SSRF 安全默认)。 |
返回值结构
成功时 HTTP 状态码为
200 OK,响应头Content-Type为image/png(或根据quality优化后的图像格式),响应体为原始二进制字节流:Node.js / Web SDK:
ArrayBufferJava SDK:
byte[]Python SDK:
bytesGo SDK:
*[]byte
错误与边界
远程 Avatars 接口默认关闭(非故障):调用
getImage、getFavicon或getScreenshot时,由于 2.6.0+ 默认收紧外部 URL 抓取以防止 SSRF 攻击,服务端会直接拒绝请求——这是平台预期安全策略,切勿将其误判为服务故障,也不要在生产环境关闭 SSRF 校验。尺寸与颜色参数越界(
400 general_argument_invalid):width/height必须在0–2000之间,size(二维码)必须在1–1000之间,background必须是不含#前缀的 6 位合法十六进制字符串(如0969da而非#0969da)。二进制流误做 JSON 解析:SDK 已自动将
Avatars响应按二进制字节流返回;若使用底层curl或自建 HTTP 客户端调用,请勿将响应体传入JSON.parse(),应使用-o <file>.png或二进制 Buffer 接收。
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 安全默认值,见「错误与边界」)。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
import { Client, Avatars, AgentbaseException } from 'agentbase-node-sdk';
import { writeFileSync } from 'node:fs';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? '<APPBASE_ENDPOINT_WITH_V1>')
.setProject(process.env.APPBASE_PROJECT_ID ?? '<APPBASE_PROJECT_ID>')
.setKey(process.env.APPBASE_API_KEY!);
{
const prepareRequest = client.prepareRequest.bind(client);
client.prepareRequest = (...args) => {
const request = prepareRequest(...args);
request.options.redirect = 'error';
return request;
};
}
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: '<TICKET_URL>',
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;
}import { Client, Avatars } from 'agentbase-web-sdk';
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
.setProject('<APPBASE_PROJECT_ID>');
const avatars = new Avatars(client);
const arrayBuffer = await avatars.getInitials({
name: 'Ada Lovelace',
width: 128,
height: 128,
background: '0969da',
});
const blobUrl = URL.createObjectURL(new Blob([arrayBuffer], { type: 'image/png' }));
console.log('头像 Blob URL:', blobUrl);import io.agentbase.Client;
import io.agentbase.services.Avatars;
import io.agentbase.enums.Flag;
import io.agentbase.exceptions.AppBaseException;
Client client = new Client()
.setEndpoint("<APPBASE_ENDPOINT_WITH_V1>")
.setProject("<APPBASE_PROJECT_ID>")
.setKey(System.getenv("APPBASE_API_KEY"));
client.setHttpClient(new okhttp3.OkHttpClient.Builder()
.followRedirects(false).followSslRedirects(false).build());
Avatars avatars = new Avatars(client);
try {
byte[] initials = avatars.getInitials("Ada Lovelace", 256L, 256L, "0969da"); // 文字头像,可设宽度/高度/背景
byte[] flag = avatars.getFlag(Flag.CHINA, 64L, 48L, 90L); // 国旗(ISO Alpha-2)
byte[] qr = avatars.getQR("<TICKET_URL>", 320L, 2L, false);
System.out.println("Initials bytes=" + initials.length + ", flag bytes=" + flag.length + ", qr bytes=" + qr.length);
} catch (AppBaseException e) {
System.err.println("HTTP " + e.getCode() + " type=" + e.getType() + ": " + e.getMessage());
}Python Server SDK 2.12.0 的默认请求可能在跳转时转发项目 API Key,暂不提供本段的 SDK 调用代码。使用本节的 REST 页签。
package main
import (
"errors"
"net/http"
"fmt"
"os"
"agentbase-go-sdk/agentbase"
)
func main() {
cl := agentbase.NewClient(
agentbase.WithEndpoint("<APPBASE_ENDPOINT_WITH_V1>"),
agentbase.WithProject("<APPBASE_PROJECT_ID>"),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
)
cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
return errors.New("refuse redirects")
}
avatars := agentbase.NewAvatars(cl)
img, _ := avatars.GetInitials(
avatars.WithGetInitialsName("Ada Lovelace"),
avatars.WithGetInitialsWidth(256),
avatars.WithGetInitialsHeight(256),
avatars.WithGetInitialsBackground("0969da"),
)
flag, _ := avatars.GetFlag("cn") // 国旗(ISO Alpha-2);另有 GetQR / GetCreditCard / GetBrowser
fmt.Println(len(*img), len(*flag))
// 2.6.0 安全默认值:远程 Image / Favicon / Screenshot 默认不可用(SSRF 防护收紧),不是故障
}(
set +x
set -e -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 1. 生成姓名首字母头像并保存为 PNG
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/avatars/initials?name=Ada+Lovelace&width=256&height=256&background=0969da" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-o initials.png
# 2. 生成二维码图片并保存为 PNG
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/avatars/qr?text=https%3A%2F%2Fappbuild-sit.oceanbase.com&size=320&margin=2" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-o qr.png
# 3. 获取国旗、浏览器与卡组织图标(远程 image / favicon / screenshots 2.6.0 默认关闭)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable --header @- -fsS "$APPBASE_ENDPOINT/avatars/flags/cn?width=64&height=48" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-o flag-cn.png
)示例指引
JavaScript / TypeScript 全量示例:../examples/javascript.md
Python 全量示例:../examples/python.md
Java 全量示例:../examples/java.md
Go 全量示例:../examples/go.md