Avatars and graphics
Overview and use cases
Avatars The service provides out-of-the-box dynamic rendering for images and icons, including: name/text initial avatar generation (getInitials), QR code image generation (getQR), country and region flag icons (getFlag), major browser icons (getBrowser), and international card network/payment brand icons (getCreditCard). In addition, the API contract also includes three remote fetching endpoints: remote image cropping (getImage), site Favicon extraction (getFavicon), and web page screenshots (getScreenshot) (subject to the default-off constraint of the 2.6.0+ SSRF security baseline).
In enterprise intelligent customer service and knowledge platforms (such as the demo project enterprise-ai-hub-210), the client and server can use Avatars to generate initial avatars with a unified visual standard in real time for support agents and visitors who have not uploaded custom avatars (such as user_zhangwei_001, user_lina_002), generate PNG QR codes for support ticket share links or mobile scan-to-login, or display visitors' country flags and browser icons in conversation audit lists.
Prerequisites
Client initialization and authentication:
Server SDK (Node.js / Java / Python / Go): initialize via
setEndpoint('https://appbuild-sit.oceanbase.com/v1'),setProject('enterprise-ai-hub-210'),setKey('<APPBASE_API_KEY>'); the API Key must have theavatars.readscope.Client / Web SDK: initialize via
setEndpoint,setProject(can be used together with a user Session).Console SDK: supports management-plane Session or short-lived JWT.
2.6.0+ security defaults (SSRF protection): remote Avatar Image (
getImage), Favicon (getFavicon), and Screenshot (getScreenshot) are unavailable by default (SSRF protection for external URLs that reject loopback/private network/cloud metadata addresses is tightened by default) — do not recommend disabling SSRF protection long-term in production to restore old behavior.
Usage workflow
Initialize
Clientand theAvatarsservice: load the project ID and authentication credentials, and constructnew Avatars(client).Generate an initial avatar (
getInitials): pass in the user namename(defaults to the current logged-in user's name when omitted, falls back to a space when there is no session), the target width and height (width/height, 0–2000 pixels), and a hexadecimal background color (background, without the#symbol, e.g.0969da).Generate a QR code (
getQR): pass in the text to encodetext(1–1024 characters, such as a support ticket link or a one-time login token), the sizesize(1–1000 pixels), the white border widthmargin(0–10), and whether to trigger an attachment downloaddownload.Fetch standard icons (
getFlag/getBrowser/getCreditCard): pass in the corresponding standard enumeration codecode(e.g. flag ISO 3166-1 Alpha-2cn, browserch/sf/ff, card networkvisa/mastercard/unionpay) plus optionalwidth,height,quality(0–100).Handle binary image responses: all
Avatarsmethods directly return the raw image byte stream (ArrayBuffer/byte[]/bytes); the server can write it directly to a file, upload it to a Storage bucket, or setContent-Type: image/pngto forward it to the frontend.
Key parameters and returns
Complete Method List and Parameter Matrix
| SDK Method (Node / Web / Java) | Python Method | Go Method | REST Endpoint | Key Parameters | Description |
|---|---|---|---|---|---|
getInitials({ name, width, height, background }) (name, width, height, and background are all optional) | get_initials(...) | GetInitials(...) | GET /v1/avatars/initials | name (≤128 characters), width (0–2000, default 500), height (0–2000, default 500), background (6-digit Hex, e.g. 0969da) | Generates the PNG bytes of an initials avatar for a name. |
getQR({ text, size, margin, download }) (size, margin, download all optional) | get_qr(...) | GetQR(...) | GET /v1/avatars/qr | text (required), size (1–1000, default 400), margin (0–10, default 1), download (boolean, default false) | Renders text or a URL into a QR code image. |
getFlag({ code, width, height, quality }) (width, height, quality all optional) | get_flag(...) | GetFlag(...) | GET /v1/avatars/flags/{code} | code (required, ISO Alpha-2 lowercase enumerations such as cn, us, jp), width (0–2000), height (0–2000), quality (0–100) | Fetches a country/region flag image. |
getBrowser({ code, width, height, quality }) (width, height, quality all optional) | get_browser(...) | GetBrowser(...) | GET /v1/avatars/browsers/{code} | code (required, enumerations such as ch Chrome, ff Firefox, sf Safari, ed Edge), width, height, quality | Fetches a browser brand icon. |
getCreditCard({ code, width, height, quality }) (width, height, quality all optional) | get_credit_card(...) | GetCreditCard(...) | GET /v1/avatars/credit-cards/{code} | code (required, enumerations such as visa, mastercard, amex, unionpay, jcb), width, height, quality | Fetches a card network/payment method icon. |
getImage({ url, width, height }) (width, height all optional) | get_image(...) | GetImage(...) | GET /v1/avatars/image | url (remote image URL), width, height | off by default since 2.6.0+ (SSRF security default). |
getFavicon({ url }) | get_favicon(...) | GetFavicon(...) | GET /v1/avatars/favicon | url (remote site URL) | off by default since 2.6.0+ (SSRF security default). |
getScreenshot({ url, ... }) | get_screenshot(...) | GetScreenshot(...) | GET /v1/avatars/screenshots | url (remote web page URL) and viewport/theme parameters | off by default since 2.6.0+ (SSRF security default). |
Return Value Structure
On success the HTTP status code is
200 OK, the response headerContent-Typeisimage/png(or an image format optimized based onquality), and the response body is the raw binary byte stream:Node.js / Web SDK:
ArrayBufferJava SDK:
byte[]Python SDK:
bytesGo SDK:
*[]byte
Errors and boundaries
Remote Avatars endpoints are off by default (not a failure): when calling
getImage,getFavicon, orgetScreenshot, because 2.6.0+ tightens external URL fetching by default to prevent SSRF attacks, the server rejects the request directly — this is the platform's expected security policy; do not misdiagnose it as a service failure, and do not disable SSRF validation in production.Size and color parameters out of range (
400 general_argument_invalid):width/heightmust be within0–2000,size(QR code) must be within1–1000, andbackgroundmust be a valid 6-digit hexadecimal string without the#prefix (e.g.0969dainstead of#0969da).Mistakenly JSON-parsing the binary stream: the SDK automatically returns
Avatarsresponses as a binary byte stream; if you use the low-levelcurlor your own HTTP client, do not pass the response body intoJSON.parse(); instead use-o <file>.pngor a binary Buffer to receive it.
SDK Category Differences
| SDK category | Coverage | Authentication method | Typical scenarios |
|---|---|---|---|
| Server SDK (Node.js / Java / Python / Go) | Full method set (returns image binary byte streams) | Project API Key (avatars.read) | Batch-generate user default avatars in the backend and archive them to Storage, generate support ticket QR code email attachments |
| Client / Web SDK (Web) | Full method set | User Session (or public project identifier) | Frontend rendering of user name-initial avatars, scan-to-login QR codes, flag and browser badges |
| Console SDK (Node.js / Java / Python / Go) | Full method set | Management-plane Session / short-lived JWT | Console member list avatars, browser/flag icon display in conversation audit endpoints |
Examples by language
Available on both client and server; the Web tab uses a user Session. Remote Image / Favicon / Screenshot are unavailable by default (2.6.0 security defaults, see "Errors and Edge Cases").
- Node.js (Server)
- Web (user 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 ?? '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. Generate a text avatar (width/height and a 6-bit hex background color can be set, without #)
const initialsBuf = await avatars.getInitials({
name: 'Zhang Wei',
width: 256,
height: 256,
background: '0969da',
});
writeFileSync('/tmp/avatar-zhangwei.png', Buffer.from(initialsBuf));
// 2. Generate a support ticket sharing QR code and flag icons
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 Safe defaults: remote getImage / getFavicon / getScreenshot are unavailable by default (tightened SSRF protection); this is not a failure
} 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('https://appbuild-sit.oceanbase.com/v1')
.setProject('enterprise-ai-hub-210');
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("https://appbuild-sit.oceanbase.com/v1")
.setProject("enterprise-ai-hub-210")
.setKey(System.getenv("APPBASE_API_KEY"));
Avatars avatars = new Avatars(client);
try {
byte[] initials = avatars.getInitials("Ada Lovelace", 256L, 256L, "0969da"); // Text avatar; width/height/background can be set
byte[] flag = avatars.getFlag(Flag.CHINA, 64L, 48L, 90L); // Flag image (ISO Alpha-2)
byte[] qr = avatars.getQR("https://appbuild-sit.oceanbase.com/tickets/TK-20261022-001", 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());
}import os
from agentbase.client import Client
from agentbase.services.avatars import Avatars
from agentbase.exception import AgentbaseException
client = (
Client()
.set_endpoint(os.environ.get('APPBASE_ENDPOINT', 'https://appbuild-sit.oceanbase.com/v1'))
.set_project(os.environ.get('APPBASE_PROJECT_ID', 'enterprise-ai-hub-210'))
.set_key(os.environ['APPBASE_API_KEY'])
)
avatars = Avatars(client)
try:
initials_bytes = avatars.get_initials(name='Ada Lovelace', width=256, height=256, background='0969da')
flag_bytes = avatars.get_flag(code='cn', width=64, height=48)
qr_bytes = avatars.get_qr(text='https://appbuild-sit.oceanbase.com/tickets/TK-20261022-001', size=320, margin=2)
print(len(initials_bytes), len(flag_bytes), len(qr_bytes))
# Remote image / favicon / screenshot unavailable by default (2.6.0 secure default)
except AgentbaseException as exc:
print(f"Avatars error {exc.code} ({exc.type}): {exc.message}")package main
import (
"fmt"
"os"
"agentbase-go-sdk/agentbase"
)
func main() {
cl := agentbase.NewClient(
agentbase.WithEndpoint("https://appbuild-sit.oceanbase.com/v1"),
agentbase.WithProject("enterprise-ai-hub-210"),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
)
avatars := agentbase.NewAvatars(cl)
img, _ := avatars.GetInitials(
avatars.WithGetInitialsName("Ada Lovelace"),
avatars.WithGetInitialsWidth(256),
avatars.WithGetInitialsHeight(256),
avatars.WithGetInitialsBackground("0969da"),
)
flag, _ := avatars.GetFlag("cn") // Flag image (ISO Alpha-2); also available GetQR / GetCreditCard / GetBrowser
fmt.Println(len(*img), len(*flag))
// 2.6.0 Safe defaults: remote Image / Favicon / Screenshot are unavailable by default (tightened SSRF protection); this is not a failure
}# 1. Generate an initials avatar and save it as PNG
curl -sS "$APPBASE_ENDPOINT/avatars/initials?name=Ada+Lovelace&width=256&height=256&background=0969da" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-o initials.png
# 2. Generate a QR code image and save it as PNG
curl -sS "$APPBASE_ENDPOINT/avatars/qr?text=https%3A%2F%2Fappbuild-sit.oceanbase.com&size=320&margin=2" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-o qr.png
# 3. Get flag, browser, and card network icons (remote image / favicon / screenshots 2.6.0 disabled by default)
curl -sS "$APPBASE_ENDPOINT/avatars/flags/cn?width=64&height=48" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-o flag-cn.pngExample Guide
JavaScript / TypeScript full example: ../examples/javascript.md
Python full example: ../examples/python.md
Java full example: ../examples/java.md
Go full example: ../examples/go.md