Docs
Contents

Avatars and graphics

Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.

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

Usage workflow

  1. Initialize Client and the Avatars service: load the project ID and authentication credentials, and construct new Avatars(client).

  2. Generate an initial avatar (getInitials): pass in the user name name (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).

  3. Generate a QR code (getQR): pass in the text to encode text (1–1024 characters, such as a support ticket link or a one-time login token), the size size (1–1000 pixels), the white border width margin (0–10), and whether to trigger an attachment download download.

  4. Fetch standard icons (getFlag / getBrowser / getCreditCard): pass in the corresponding standard enumeration code code (e.g. flag ISO 3166-1 Alpha-2 cn, browser ch / sf / ff, card network visa / mastercard / unionpay) plus optional width, height, quality (0–100).

  5. Handle binary image responses: all Avatars methods 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 set Content-Type: image/png to forward it to the frontend.

Key parameters and returns

Complete Method List and Parameter Matrix

SDK Method (Node / Web / Java)Python MethodGo MethodREST EndpointKey ParametersDescription
getInitials({ name, width, height, background }) (name, width, height, and background are all optional)get_initials(...)GetInitials(...)GET /v1/avatars/initialsname (≤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/qrtext (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, qualityFetches 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, qualityFetches a card network/payment method icon.
getImage({ url, width, height }) (width, height all optional)get_image(...)GetImage(...)GET /v1/avatars/imageurl (remote image URL), width, heightoff by default since 2.6.0+ (SSRF security default).
getFavicon({ url })get_favicon(...)GetFavicon(...)GET /v1/avatars/faviconurl (remote site URL)off by default since 2.6.0+ (SSRF security default).
getScreenshot({ url, ... })get_screenshot(...)GetScreenshot(...)GET /v1/avatars/screenshotsurl (remote web page URL) and viewport/theme parametersoff by default since 2.6.0+ (SSRF security default).

Return Value Structure

Errors and boundaries

SDK Category Differences

SDK categoryCoverageAuthentication methodTypical 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 setUser 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 setManagement-plane Session / short-lived JWTConsole 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").

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. 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: '<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 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;
}

Example Guide