Docs
文档目录

头像与图形 API

头像与图形资源生成:姓名首字母头像、二维码、国旗、浏览器/卡组织图标、远程图片抓取与站点截图。

服务与资源边界

头像与图形(Avatars)API 提供无状态的动态图像渲染、二维码生成、远程图片安全代理缩放与无头浏览器网页截图能力,所有端点直接返回图像二进制字节流(如 image/png、image/jpeg、image/webp),并内置針對内网地址的 SSRF 防护。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。

端点总览

本服务包含 8 个只读 GET 端点,分为静态图标渲染(浏览器、信用卡、ISO 国旗)、动态图形生成(姓名首字母头像、QR 二维码)与远程站点抓取(图片裁剪代理、Favicon 提取、无头浏览器网页截图)。

端点清单

方法 + 路径用途
GET /avatars/browsers/{code}浏览器图标
GET /avatars/credit-cards/{code}信用卡图标
GET /avatars/flags/{code}国旗(ISO Alpha-2)
GET /avatars/image抓取并缩放远程图片
GET /avatars/favicon站点 favicon
GET /avatars/initials姓名首字母头像
GET /avatars/qr二维码
GET /avatars/screenshots网页截图

端点详解

全部端点均通过 Query 参数控制输出尺寸(width/height)与图像质量(quality);远程抓取类端点(/avatars/image、/avatars/favicon、/avatars/screenshots)默认拒绝 RFC 1918 私网目标且不跟随跨协议重定向,/avatars/screenshots 独立适用 60 次/小时的速率限制。

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。

Avatars

GET /v1/avatars/browsers/{code}

返回浏览器图标 PNG:code 为用户会话中的浏览器代码。

输入:

参数位置类型必填默认/枚举说明
codepathstring是枚举 aa, an, ch, ci, cm, cr, ff, sf …浏览器代码,14 种: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)。
widthqueryinteger否默认 100宽度 0–2000,默认 100。
heightqueryinteger否默认 100高度 0–2000,默认 100。
qualityqueryinteger否默认 -1质量 0–100;默认 -1 表示保持原图质量。

输出:200 + 图像二进制(PNG)。

调用示例:

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

响应示例:响应为图像二进制(Content-Type: image/png),此处不展示 JSON。

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

返回信用卡品牌图标:code 为品牌代码。

输入:

参数位置类型必填默认/枚举说明
codepathstring是枚举 amex, argencard, cabal, cencosud, diners, discover, elo, hipercard …信用卡代码,17 种:amex、argencard、cabal、cencosud、diners、discover、elo、hipercard、jcb、mastercard、naranja、targeta-shopping、unionpay、visa、mir、maestro、rupay。
widthqueryinteger否默认 100宽度 0–2000,默认 100。
heightqueryinteger否默认 100高度 0–2000,默认 100。
qualityqueryinteger否默认 -1质量 0–100;默认 -1 保持原图质量。

输出:200 + 图像二进制(PNG)。

调用示例:

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

响应示例:响应为图像二进制,此处不展示 JSON。

GET /v1/avatars/flags/{code}

返回国旗图标:code 为 ISO 3166-1 两位国家代码。

输入:

参数位置类型必填默认/枚举说明
codepathstring是枚举 af, ao, al, ad, ae, ar, am, ag …ISO 3166-1 Alpha-2 国家代码(如 cn、us、jp),全量枚举与 /locale/countries 返回的 code 一致。
widthqueryinteger否默认 100宽度 0–2000,默认 100。
heightqueryinteger否默认 100高度 0–2000,默认 100。
qualityqueryinteger否默认 -1质量 0–100;默认 -1 保持原图质量。

输出:200 + 图像二进制(PNG)。

调用示例:

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

响应示例:响应为图像二进制,此处不展示 JSON。

GET /v1/avatars/image

抓取远程图片并裁剪缩放后返回:适用于第三方图片代理展示与强制 TLS 化。

输入:

参数位置类型必填默认/枚举说明
urlquerystring是—要裁剪的远程图片 URL。
widthqueryinteger否默认 400宽度 0–2000,默认 400。
heightqueryinteger否默认 400高度 0–2000,默认 400。

输出:200 + 图像二进制。

调用示例:

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

响应示例:响应为图像二进制,此处不展示 JSON。

GET /v1/avatars/favicon

抓取任意网站的 favicon 并返回。

输入:

参数位置类型必填默认/枚举说明
urlquerystring是—目标网站 URL。

输出:200 + 图像二进制。

调用示例:

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

响应示例:响应为图像二进制,此处不展示 JSON。

GET /v1/avatars/initials

生成姓名首字母头像:默认取当前登录用户名或邮箱首字母,背景色按名字稳定随机(同名同色)。

输入:

参数位置类型必填默认/枚举说明
namequerystring否默认 ""全名,≤128 字符;为空时用当前用户名 / 邮箱,无用户时返回空头像。
widthqueryinteger否默认 500宽度 0–2000,默认 500。
heightqueryinteger否默认 500高度 0–2000,默认 500。
backgroundquerystring否默认 ""背景色(如 ff0055);默认按名字稳定随机。

输出:200 + 图像二进制(PNG)。

调用示例:

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

响应示例:响应为图像二进制,此处不展示 JSON。

GET /v1/avatars/qr

把文本转换为二维码图片:可调尺寸、留白与下载头。

输入:

参数位置类型必填默认/枚举说明
textquerystring是—要编码的文本内容。
sizequeryinteger否默认 400二维码边长 1–1000,默认 400。
marginqueryinteger否默认 1留白 0–10,默认 1。
downloadqueryboolean否默认 falsetrue 时附加 Content-Disposition: attachment 头触发浏览器下载。

输出:200 + 图像二进制(PNG)。

调用示例:

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

响应示例:响应为图像二进制,此处不展示 JSON。

GET /v1/avatars/screenshots

用无头浏览器渲染目标网页并截图:可配置视口、主题、UA、地理模拟、权限与输出格式。限流 60 次/小时。

输入:

参数位置类型必填默认/枚举说明
urlquerystring是—要截图的网页 URL。
headersqueryobject否默认 {}附加 HTTP 请求头对象(JSON 编码在 query 中),默认空。
viewportWidthqueryinteger否默认 1280视口宽度 1–1920,默认 1280。
viewportHeightqueryinteger否默认 720视口高度 1–1080,默认 720。
scalequerynumber否默认 1缩放系数 0.1–3,默认 1。
themequerystring否枚举 light, dark;默认 "light"主题:light / dark,默认 light。
userAgentquerystring否默认 ""自定义 User-Agent,默认浏览器默认值。
fullpagequeryboolean否默认 falsetrue 截取整页滚动,默认仅视口。
localequerystring否默认 ""浏览器 locale(如 zh-CN)。
timezonequerystring否枚举 africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …;默认 ""IANA 时区(如 asia/shanghai)。
latitudequerynumber否默认 0地理模拟纬度 -90–90,默认 0。
longitudequerynumber否默认 0地理模拟经度 -180–180,默认 0。
accuracyquerynumber否默认 0地理模拟精度(米)0–100000,默认 0。
touchqueryboolean否默认 false是否启用触控。
permissionsquerystring[]否默认 []授予的浏览器权限数组(如 geolocation、camera、microphone)。
sleepqueryinteger否默认 0截图前等待秒数 0–10,默认 0。
widthqueryinteger否默认 0输出图宽:0 为原始宽,1–2000 显式指定,默认 0。
heightqueryinteger否默认 0输出图高:0 为原始高,1–2000 显式指定,默认 0。
qualityqueryinteger否默认 -1截图质量 0–100;默认 -1 保持默认质量。
outputquerystring否枚举 jpg, jpeg, png, webp, heic, avif, gif;默认 ""输出格式:jpg / jpeg / png / webp / heic / avif / gif。

输出:200 + 图像二进制(格式由 output 决定)。

调用示例:

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

响应示例:响应为图像二进制,此处不展示 JSON。

错误与边界

与 Server SDK 的对应

service.method端点
Avatars.getBrowser / getCreditCard / getFlag / getImage / getFavicon / getInitials / getQR / getScreenshot/avatars*