头像与图形 API
头像与图形资源生成:姓名首字母头像、二维码、国旗、浏览器/卡组织图标、远程图片抓取与站点截图。
服务与资源边界
头像与图形(Avatars)API 提供无状态的动态图像渲染、二维码生成、远程图片安全代理缩放与无头浏览器网页截图能力,所有端点直接返回图像二进制字节流(如 image/png、image/jpeg、image/webp),并内置針對内网地址的 SSRF 防护。
资源与基础路径
Base URL:
https://<your-endpoint>/v1。路径前缀
/avatars;无状态端点,返回图像字节。
认证与权限
认证与请求头约定见 通用约定。
spec 认证标注为
Project + Session(客户端面工具),scopeavatars.read;经 Server SDK 以项目头调用。
端点总览
本服务包含 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 为用户会话中的浏览器代码。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
code | path | string | 是 | 枚举 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)。 |
width | query | integer | 否 | 默认 100 | 宽度 0–2000,默认 100。 |
height | query | integer | 否 | 默认 100 | 高度 0–2000,默认 100。 |
quality | query | integer | 否 | 默认 -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 为品牌代码。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
code | path | string | 是 | 枚举 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。 |
width | query | integer | 否 | 默认 100 | 宽度 0–2000,默认 100。 |
height | query | integer | 否 | 默认 100 | 高度 0–2000,默认 100。 |
quality | query | integer | 否 | 默认 -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 两位国家代码。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
code | path | string | 是 | 枚举 af, ao, al, ad, ae, ar, am, ag … | ISO 3166-1 Alpha-2 国家代码(如 cn、us、jp),全量枚举与 /locale/countries 返回的 code 一致。 |
width | query | integer | 否 | 默认 100 | 宽度 0–2000,默认 100。 |
height | query | integer | 否 | 默认 100 | 高度 0–2000,默认 100。 |
quality | query | integer | 否 | 默认 -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 化。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
url | query | string | 是 | — | 要裁剪的远程图片 URL。 |
width | query | integer | 否 | 默认 400 | 宽度 0–2000,默认 400。 |
height | query | integer | 否 | 默认 400 | 高度 0–2000,默认 400。 |
输出:200 + 图像二进制。
不跟随 HTTP 重定向;目标为内网地址时被 SSRF 防护拒绝。
调用示例:
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 并返回。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
url | query | string | 是 | — | 目标网站 URL。 |
输出:200 + 图像二进制。
不跟随 HTTP 重定向;内网地址被 SSRF 防护拒绝。
调用示例:
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
生成姓名首字母头像:默认取当前登录用户名或邮箱首字母,背景色按名字稳定随机(同名同色)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | query | string | 否 | 默认 "" | 全名,≤128 字符;为空时用当前用户名 / 邮箱,无用户时返回空头像。 |
width | query | integer | 否 | 默认 500 | 宽度 0–2000,默认 500。 |
height | query | integer | 否 | 默认 500 | 高度 0–2000,默认 500。 |
background | query | string | 否 | 默认 "" | 背景色(如 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
把文本转换为二维码图片:可调尺寸、留白与下载头。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
text | query | string | 是 | — | 要编码的文本内容。 |
size | query | integer | 否 | 默认 400 | 二维码边长 1–1000,默认 400。 |
margin | query | integer | 否 | 默认 1 | 留白 0–10,默认 1。 |
download | query | boolean | 否 | 默认 false | true 时附加 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 次/小时。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
url | query | string | 是 | — | 要截图的网页 URL。 |
headers | query | object | 否 | 默认 {} | 附加 HTTP 请求头对象(JSON 编码在 query 中),默认空。 |
viewportWidth | query | integer | 否 | 默认 1280 | 视口宽度 1–1920,默认 1280。 |
viewportHeight | query | integer | 否 | 默认 720 | 视口高度 1–1080,默认 720。 |
scale | query | number | 否 | 默认 1 | 缩放系数 0.1–3,默认 1。 |
theme | query | string | 否 | 枚举 light, dark;默认 "light" | 主题:light / dark,默认 light。 |
userAgent | query | string | 否 | 默认 "" | 自定义 User-Agent,默认浏览器默认值。 |
fullpage | query | boolean | 否 | 默认 false | true 截取整页滚动,默认仅视口。 |
locale | query | string | 否 | 默认 "" | 浏览器 locale(如 zh-CN)。 |
timezone | query | string | 否 | 枚举 africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …;默认 "" | IANA 时区(如 asia/shanghai)。 |
latitude | query | number | 否 | 默认 0 | 地理模拟纬度 -90–90,默认 0。 |
longitude | query | number | 否 | 默认 0 | 地理模拟经度 -180–180,默认 0。 |
accuracy | query | number | 否 | 默认 0 | 地理模拟精度(米)0–100000,默认 0。 |
touch | query | boolean | 否 | 默认 false | 是否启用触控。 |
permissions | query | string[] | 否 | 默认 [] | 授予的浏览器权限数组(如 geolocation、camera、microphone)。 |
sleep | query | integer | 否 | 默认 0 | 截图前等待秒数 0–10,默认 0。 |
width | query | integer | 否 | 默认 0 | 输出图宽:0 为原始宽,1–2000 显式指定,默认 0。 |
height | query | integer | 否 | 默认 0 | 输出图高:0 为原始高,1–2000 显式指定,默认 0。 |
quality | query | integer | 否 | 默认 -1 | 截图质量 0–100;默认 -1 保持默认质量。 |
output | query | string | 否 | 枚举 jpg, jpeg, png, webp, heic, avif, gif;默认 "" | 输出格式:jpg / jpeg / png / webp / heic / avif / gif。 |
输出:200 + 图像二进制(格式由 output 决定)。
限流 60 次/小时;目标为内网地址时被 SSRF 防护拒绝。
调用示例:
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。
错误与边界
Avatars 远程抓取(image/favicon/screenshots)有目标站点访问限制与 SSRF 防护:内网地址被拒绝。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Avatars.getBrowser / getCreditCard / getFlag / getImage / getFavicon / getInitials / getQR / getScreenshot | /avatars* |
2.12.0 接口与兼容增量
以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
GET /avatars/screenshots | avatars.read | avatars.getScreenshot |
GET /avatars/screenshots
获取网页截图
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
url | query | 是 | string | format=url | 需要截取的网站 URL。 |
headers | query | 否 | object | default=[] | 浏览器请求携带的 HTTP 请求头,默认为空。 |
viewportWidth | query | 否 | integer | format=int32; default=1280 | 浏览器视口宽度,取 1–1920 的整数,默认 1280。 |
viewportHeight | query | 否 | integer | format=int32; default=720 | 浏览器视口高度,取 1–1080 的整数,默认 720。 |
scale | query | 否 | number | format=float; default=1 | 浏览器缩放系数,取 0.1–3,默认 1。 |
theme | query | 否 | string | enum=light, dark; default="light" | 浏览器主题,可选 "light" 或 "dark",默认 "light"。 |
userAgent | query | 否 | string | default="" | 自定义用户代理字符串,默认使用浏览器配置。 |
fullpage | query | 否 | boolean | default=false | 是否截取完整页面:0 仅截取视口,1 截取整页;默认 0。 |
locale | query | 否 | string | default="" | 浏览器区域设置,例如 "en-US"、"fr-FR";默认使用浏览器配置。 |
timezone | query | 否 | string | enum=africa/abidjan, africa/accra, africa/addis_ababa, africa/algiers, africa/asmara, africa/bamako, africa/bangui, africa/banjul …; default="" | IANA 时区标识,例如 "America/New_York";默认使用浏览器配置。 |
latitude | query | 否 | number | format=float; default=0 | 地理位置纬度,取 -90–90,默认 0。 |
longitude | query | 否 | number | format=float; default=0 | 地理位置经度,取 -180–180,默认 0。 |
accuracy | query | 否 | number | format=float; default=0 | 地理位置精度,单位米,取 0–100000,默认 0。 |
touch | query | 否 | boolean | default=false | 是否启用触摸支持:0 为关闭,1 为开启;默认 0。 |
permissions | query | 否 | array[string] | default=[] | 授予浏览器的权限名称数组,例如 ["geolocation", "camera", "microphone"];默认为空。 |
sleep | query | 否 | integer | format=int32; default=0 | 截图前等待的秒数,取 0–10 的整数,默认 0。 |
width | query | 否 | integer | format=int32; default=0 | 输出图片宽度;0 使用原宽度,也可设置 1–2000 的整数,默认 0。 |
height | query | 否 | integer | format=int32; default=0 | 输出图片高度;0 使用原高度,也可设置 1–2000 的整数,默认 0。 |
quality | query | 否 | integer | format=int32; default=-1 | 截图质量,取 0–100 的整数;默认保留原图片质量。 |
output | query | 否 | string | enum=jpg, jpeg, png, webp, heic, avif, gif; default="" | 输出格式,可选 jpeg、jpg、png、gif、webp。 |
成功响应:HTTP 200 — Image.
错误与重试边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。