Docs
Contents

Avatars and Graphics API

Avatar and graphics resource generation: initials avatars, QR codes, flags, browser/card network icons, remote image fetching, and website screenshots.

Service and resource boundaries

The Avatars and Graphics API provides stateless dynamic image rendering, QR code generation, secure proxied scaling of remote images, and headless browser webpage screenshots. All endpoints directly return an image binary byte stream (such as image/png, image/jpeg, image/webp), with built-in SSRF protection against internal network addresses.

Resources and Base Paths

Authentication and Permissions

See general conventions for authentication and request header conventions.

Endpoint overview

This service contains 8 read-only GET endpoints, divided into static icon rendering (browsers, credit cards, ISO flags), dynamic graphic generation (initials avatars, QR codes), and remote site fetching (image cropping proxy, favicon extraction, headless browser webpage screenshots).

Endpoint List

Method + pathPurpose
GET /avatars/browsers/{code}Browser icon
GET /avatars/credit-cards/{code}Credit card icon
GET /avatars/flags/{code}Flag (ISO Alpha-2)
GET /avatars/imageFetch and scale remote image
GET /avatars/faviconSite favicon
GET /avatars/initialsInitials avatar
GET /avatars/qrQR code
GET /avatars/screenshotsWebpage screenshot

Endpoint details

All endpoints control output size (width/height) and image quality (quality) via query parameters; remote fetching endpoints (/avatars/image, /avatars/favicon, /avatars/screenshots) reject RFC 1918 private network targets by default and do not follow cross-protocol redirects; /avatars/screenshots has its own rate limit of 60 requests/hour.

Requests and Responses

Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), call examples (copyable curl) and response examples. Endpoints marked with "generalized schema any" return the JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for specific fields.

Avatars

GET /v1/avatars/browsers/{code}

Returns a browser icon PNG: code is the browser code from the user session.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
codepathstringYesEnum aa, an, ch, ci, cm, cr, ff, sf …Browser code, 14 types: aa (Avant), an (Android), ch (Chrome), ci (Chrome iOS), cm (Camino), cr (Chromium), ff (Firefox), sf (Safari), mf (Microsoft Edge), ps (Safari iOS), oi (Opera Mini), om (Opera), op (Opera Next), on (IE).
widthqueryintegerNoDefault 100Width 0–2000, default 100.
heightqueryintegerNoDefault 100Height 0–2000, default 100.
qualityqueryintegerNoDefault -1Quality 0–100; default -1 means preserving the original image quality.

output: 200 + image binary (PNG).

Call example:

curl "https://<your-endpoint>/v1/avatars/browsers/ff?width=100&height=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output browser.png

response example: the response is image binary (Content-Type: image/png); JSON is not shown here.

GET /v1/avatars/credit-cards/{code}

Returns a credit card brand icon: code is the brand code.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
codepathstringYesEnum amex, argencard, cabal, cencosud, diners, discover, elo, hipercard …Credit card code, 17 types: amex, argencard, cabal, cencosud, diners, discover, elo, hipercard, jcb, mastercard, naranja, targeta-shopping, unionpay, visa, mir, maestro, rupay.
widthqueryintegerNoDefault 100Width 0–2000, default 100.
heightqueryintegerNoDefault 100Height 0–2000, default 100.
qualityqueryintegerNoDefault -1Quality 0–100; default -1 preserves the original image quality.

output: 200 + image binary (PNG).

Call example:

curl "https://<your-endpoint>/v1/avatars/credit-cards/visa?width=100&height=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output card.png

response example: the response is image binary; JSON is not shown here.

GET /v1/avatars/flags/{code}

Returns a flag icon: code is the two-letter ISO 3166-1 country code.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
codepathstringYesEnum af, ao, al, ad, ae, ar, am, ag …ISO 3166-1 Alpha-2 country code (such as cn, us, jp); the full enumeration matches the code returned by /locale/countries.
widthqueryintegerNoDefault 100Width 0–2000, default 100.
heightqueryintegerNoDefault 100Height 0–2000, default 100.
qualityqueryintegerNoDefault -1Quality 0–100; default -1 preserves the original image quality.

output: 200 + image binary (PNG).

Call example:

curl "https://<your-endpoint>/v1/avatars/flags/cn?width=100&height=100" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output flag.png

response example: the response is image binary; JSON is not shown here.

GET /v1/avatars/image

Fetches a remote image and returns it after cropping and scaling: suitable for proxied display of third-party images and enforcing TLS.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
urlquerystringYes—URL of the remote image to crop.
widthqueryintegerNoDefault 400Width 0–2000, default 400.
heightqueryintegerNoDefault 400Height 0–2000, default 400.

output: 200 + image binary.

Call example:

curl "https://<your-endpoint>/v1/avatars/image?url=https%3A%2F%2Fexample.com%2Fphoto.jpg&width=400&height=400" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output photo.jpg

response example: the response is image binary; JSON is not shown here.

GET /v1/avatars/favicon

Fetches the favicon of any website and returns it.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
urlquerystringYes—URL of the target website.

output: 200 + image binary.

Call example:

curl "https://<your-endpoint>/v1/avatars/favicon?url=https%3A%2F%2Fexample.com" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output favicon.png

response example: the response is image binary; JSON is not shown here.

GET /v1/avatars/initials

Generates an initials avatar: by default takes the initials of the currently logged-in username or email, with a background color deterministically randomized by name (same name, same color).

Input:

ParameterLocationTypeRequiredDefault/enumDescription
namequerystringNoDefault ""Full name, ≤128 characters; if empty, uses the current username / email; returns an empty avatar if there is no user.
widthqueryintegerNoDefault 500Width 0–2000, default 500.
heightqueryintegerNoDefault 500Height 0–2000, default 500.
backgroundquerystringNoDefault ""Background color (such as ff0055); defaults to deterministic random based on the name.

output: 200 + image binary (PNG).

Call example:

curl "https://<your-endpoint>/v1/avatars/initials?name=Ada%20Lovelace&width=500&height=500" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output initials.png

response example: the response is image binary; JSON is not shown here.

GET /v1/avatars/qr

Converts text into a QR code image: size, margin, and download header are configurable.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
textquerystringYes—Text content to encode.
sizequeryintegerNoDefault 400QR code side length 1–1000, default 400.
marginqueryintegerNoDefault 1Margin 0–10, default 1.
downloadquerybooleanNoDefault falseWhen true, adds the Content-Disposition: attachment header to trigger a browser download.

output: 200 + image binary (PNG).

Call example:

curl "https://<your-endpoint>/v1/avatars/qr?text=https%3A%2F%2Fexample.com%2Finvite&size=400&margin=1&download=false" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output qr.png

response example: the response is image binary; JSON is not shown here.

GET /v1/avatars/screenshots

Renders the target webpage with a headless browser and takes a screenshot: viewport, theme, UA, geo spoofing, permissions, and output format are configurable. Rate limited to 60 requests/hour.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
urlquerystringYes—URL of the webpage to screenshot.
headersqueryobjectNoDefault {}Additional HTTP request headers object (JSON-encoded in the query), empty by default.
viewportWidthqueryintegerNoDefault 1280Viewport width 1–1920, default 1280.
viewportHeightqueryintegerNoDefault 720Viewport height 1–1080, default 720.
scalequerynumberNoDefault 1Scale factor 0.1–3, default 1.
themequerystringNoEnum light, dark; default "light"Theme: light / dark, default light.
userAgentquerystringNoDefault ""Custom User-Agent; defaults to the browser's default value.
fullpagequerybooleanNoDefault falsetrue Capture the full scrollable page; by default only the viewport is captured.
localequerystringNoDefault ""Browser locale (e.g. zh-CN).
timezonequerystringNoEnum africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default ""IANA time zone (e.g. asia/shanghai).
latitudequerynumberNoDefault 0Geolocation simulation latitude -90–90, default 0.
longitudequerynumberNoDefault 0Geolocation simulation longitude -180–180, default 0.
accuracyquerynumberNoDefault 0Geolocation simulation accuracy (meters) 0–100000, default 0.
touchquerybooleanNoDefault falseWhether to enable touch.
permissionsquerystring[]NoDefault []Array of granted browser permissions (e.g. geolocation, camera, microphone).
sleepqueryintegerNoDefault 0Seconds to wait before the screenshot 0–10, default 0.
widthqueryintegerNoDefault 0Output image width: 0 for original width, 1–2000 for explicit specification, default 0.
heightqueryintegerNoDefault 0Output image height: 0 for original height, 1–2000 for explicit specification, default 0.
qualityqueryintegerNoDefault -1Screenshot quality 0–100; default -1 keeps the default quality.
outputquerystringNoEnum jpg, jpeg, png, webp, heic, avif, gif; default ""Output format: jpg / jpeg / png / webp / heic / avif / gif.

Output: 200 + image binary (format determined by output).

Call example:

curl "https://<your-endpoint>/v1/avatars/screenshots?url=https%3A%2F%2Fexample.com&viewportWidth=1920&viewportHeight=1080&theme=dark&fullpage=true&sleep=3&output=jpeg&quality=85" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  --output shot.jpeg

response example: the response is image binary; JSON is not shown here.

Errors and boundaries

Correspondence with the Server SDK

service.methodEndpoint
Avatars.getBrowser / getCreditCard / getFlag / getImage / getFavicon / getInitials / getQR / getScreenshot/avatars*