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
Base URL:
https://<your-endpoint>/v1。Path prefix
/avatars; stateless endpoints that return image bytes.
Authentication and Permissions
See general conventions for authentication and request header conventions.
The spec marks authentication as
Project + Session(client-facing tool), scopeavatars.read; called via the Server SDK with project headers.
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 + path | Purpose |
|---|---|
GET /avatars/browsers/{code} | Browser icon |
GET /avatars/credit-cards/{code} | Credit card icon |
GET /avatars/flags/{code} | Flag (ISO Alpha-2) |
GET /avatars/image | Fetch and scale remote image |
GET /avatars/favicon | Site favicon |
GET /avatars/initials | Initials avatar |
GET /avatars/qr | QR code |
GET /avatars/screenshots | Webpage 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
code | path | string | Yes | Enum 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). |
width | query | integer | No | Default 100 | Width 0–2000, default 100. |
height | query | integer | No | Default 100 | Height 0–2000, default 100. |
quality | query | integer | No | Default -1 | Quality 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.pngresponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
code | path | string | Yes | Enum 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. |
width | query | integer | No | Default 100 | Width 0–2000, default 100. |
height | query | integer | No | Default 100 | Height 0–2000, default 100. |
quality | query | integer | No | Default -1 | Quality 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.pngresponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
code | path | string | Yes | Enum 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. |
width | query | integer | No | Default 100 | Width 0–2000, default 100. |
height | query | integer | No | Default 100 | Height 0–2000, default 100. |
quality | query | integer | No | Default -1 | Quality 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.pngresponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
url | query | string | Yes | — | URL of the remote image to crop. |
width | query | integer | No | Default 400 | Width 0–2000, default 400. |
height | query | integer | No | Default 400 | Height 0–2000, default 400. |
output: 200 + image binary.
Does not follow HTTP redirects; internal network addresses are rejected by SSRF protection.
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.jpgresponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
url | query | string | Yes | — | URL of the target website. |
output: 200 + image binary.
Does not follow HTTP redirects; internal network addresses are rejected by SSRF protection.
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.pngresponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | query | string | No | Default "" | Full name, ≤128 characters; if empty, uses the current username / email; returns an empty avatar if there is no user. |
width | query | integer | No | Default 500 | Width 0–2000, default 500. |
height | query | integer | No | Default 500 | Height 0–2000, default 500. |
background | query | string | No | Default "" | 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.pngresponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
text | query | string | Yes | — | Text content to encode. |
size | query | integer | No | Default 400 | QR code side length 1–1000, default 400. |
margin | query | integer | No | Default 1 | Margin 0–10, default 1. |
download | query | boolean | No | Default false | When 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.pngresponse 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:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
url | query | string | Yes | — | URL of the webpage to screenshot. |
headers | query | object | No | Default {} | Additional HTTP request headers object (JSON-encoded in the query), empty by default. |
viewportWidth | query | integer | No | Default 1280 | Viewport width 1–1920, default 1280. |
viewportHeight | query | integer | No | Default 720 | Viewport height 1–1080, default 720. |
scale | query | number | No | Default 1 | Scale factor 0.1–3, default 1. |
theme | query | string | No | Enum light, dark; default "light" | Theme: light / dark, default light. |
userAgent | query | string | No | Default "" | Custom User-Agent; defaults to the browser's default value. |
fullpage | query | boolean | No | Default false | true Capture the full scrollable page; by default only the viewport is captured. |
locale | query | string | No | Default "" | Browser locale (e.g. zh-CN). |
timezone | query | string | No | Enum 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). |
latitude | query | number | No | Default 0 | Geolocation simulation latitude -90–90, default 0. |
longitude | query | number | No | Default 0 | Geolocation simulation longitude -180–180, default 0. |
accuracy | query | number | No | Default 0 | Geolocation simulation accuracy (meters) 0–100000, default 0. |
touch | query | boolean | No | Default false | Whether to enable touch. |
permissions | query | string[] | No | Default [] | Array of granted browser permissions (e.g. geolocation, camera, microphone). |
sleep | query | integer | No | Default 0 | Seconds to wait before the screenshot 0–10, default 0. |
width | query | integer | No | Default 0 | Output image width: 0 for original width, 1–2000 for explicit specification, default 0. |
height | query | integer | No | Default 0 | Output image height: 0 for original height, 1–2000 for explicit specification, default 0. |
quality | query | integer | No | Default -1 | Screenshot quality 0–100; default -1 keeps the default quality. |
output | query | string | No | Enum 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).
Rate limit: 60 requests/hour; requests targeting intranet addresses are rejected by SSRF protection.
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.jpegresponse example: the response is image binary; JSON is not shown here.
Errors and boundaries
Avatars remote fetching (image/favicon/screenshots) is subject to target site access restrictions and SSRF protection: intranet addresses are rejected.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Avatars.getBrowser / getCreditCard / getFlag / getImage / getFavicon / getInitials / getQR / getScreenshot | /avatars* |
2.12.0 endpoints and compatibility
Paths below are relative to /v1. Server requests carry X-Appwrite-Project and X-Appwrite-Key; keep the key on the server. Scopes below are necessary; dataset access, ownership and resource state may add checks. HTTP 202 means accepted; use the returned operation identifier to read its terminal result.
| HTTP | Scope | SDK |
|---|---|---|
GET /avatars/screenshots | avatars.read | avatars.getScreenshot |
GET /avatars/screenshots
Get webpage screenshot
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
url | query | yes | string | format=url | Website URL which you want to capture. |
headers | query | no | object | default=[] | HTTP headers to send with the browser request. Defaults to empty. |
viewportWidth | query | no | integer | format=int32; default=1280 | Browser viewport width. Pass an integer between 1 to 1920. Defaults to 1280. |
viewportHeight | query | no | integer | format=int32; default=720 | Browser viewport height. Pass an integer between 1 to 1080. Defaults to 720. |
scale | query | no | number | format=float; default=1 | Browser scale factor. Pass a number between 0.1 to 3. Defaults to 1. |
theme | query | no | string | enum=light, dark; default="light" | Browser theme. Pass "light" or "dark". Defaults to "light". |
userAgent | query | no | string | default="" | Custom user agent string. Defaults to browser default. |
fullpage | query | no | boolean | default=false | Capture full page scroll. Pass 0 for viewport only, or 1 for full page. Defaults to 0. |
locale | query | no | string | default="" | Browser locale (e.g., "en-US", "fr-FR"). Defaults to browser default. |
timezone | query | no | string | enum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="" | IANA timezone identifier (e.g., "America/New_York", "Europe/London"). Defaults to browser default. |
latitude | query | no | number | format=float; default=0 | Geolocation latitude. Pass a number between -90 to 90. Defaults to 0. |
longitude | query | no | number | format=float; default=0 | Geolocation longitude. Pass a number between -180 to 180. Defaults to 0. |
accuracy | query | no | number | format=float; default=0 | Geolocation accuracy in meters. Pass a number between 0 to 100000. Defaults to 0. |
touch | query | no | boolean | default=false | Enable touch support. Pass 0 for no touch, or 1 for touch enabled. Defaults to 0. |
permissions | query | no | array[string] | default=[] | Browser permissions to grant. Pass an array of permission names like ["geolocation", "camera", "microphone"]. Defaults to empty. |
sleep | query | no | integer | format=int32; default=0 | Wait time in seconds before taking the screenshot. Pass an integer between 0 to 10. Defaults to 0. |
width | query | no | integer | format=int32; default=0 | Output image width. Pass 0 to use original width, or an integer between 1 to 2000. Defaults to 0 (original width). |
height | query | no | integer | format=int32; default=0 | Output image height. Pass 0 to use original height, or an integer between 1 to 2000. Defaults to 0 (original height). |
quality | query | no | integer | format=int32; default=-1 | Screenshot quality. Pass an integer between 0 to 100. Defaults to keep existing image quality. |
output | query | no | string | enum=jpg, jpeg, png, webp, heic, avif, gif; default="" | Output format type (jpeg, jpg, png, gif and webp). |
Success response: HTTP 200 — Image.
Errors and retries
400/422: check types, enumerations and rules. 401/403: verify identity and scopes; dataset analyses additionally require trace and dataset read access. 404: check that the resource exists in the current project. 409: read current state before deciding to retry. 429: honor Retry-After. After 5xx or network loss, inspect operation state first. Preserve an idempotency key across retries; change it only for a deliberate new operation. Confirm deletion and clearing targets before writing.