对象存储 API
桶(bucket)与文件(file)管理:桶的创建与策略配置、文件上传(含大文件分片续传)、元数据与权限维护、下载/预览/内联查看。文件短时访问令牌见 file-tokens,桶/文件双层权限语义见 permissions。
服务与资源边界
对象存储 API(/v1/storage/*)负责管理项目内的存储桶(Bucket,如展示项目中的知识库源文件桶 kb_enterprise_docs 与智能体多媒体桶 agent_multimedia_bucket)及文件(File)全生命周期:支持最大单文件大小限制、扩展名白名单、Gzip/Zstd 压缩、静态加密、ClamAV 病毒扫描、5MB 分片断点续传、在线图片裁剪/格式转换预览(/preview),并与知识库文档摄取和 Memory 多模态解析无缝衔接。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/storage。资源:
bucket(桶,{bucketId})、file(文件,{fileId},属某桶)。ID 约束:自定义 ID 用 a-z、A-Z、0-9、
.、-、_,不能以特殊字符开头,最长 36 字符。
认证与权限
认证与请求头约定见 通用约定。本域 scope:
| scope | 覆盖 |
|---|---|
buckets.read / buckets.write | 桶 CRUD |
files.read / files.write | 文件上传、读取、下载/预览/查看、更新、删除 |
资源级权限(桶 $permissions + fileSecurity、文件 $permissions)约束用户身份访问;API Key 访问只做 scope 检查。权限不匹配时下载/预览返回 404 而非 403(不泄露存在性)。
端点总览
Storage 模块共提供 13 个端点:包括 5 个存储桶管理端点(/storage/buckets*)与 8 个文件管理及流式读取端点(/storage/buckets/{bucketId}/files*,含 download、preview、view 三种二进制输出模式)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
GET /storage/buckets | 列出桶 |
POST /storage/buckets | 创建桶 |
GET /storage/buckets/{bucketId} | 获取桶 |
PUT /storage/buckets/{bucketId} | 更新桶配置 |
DELETE /storage/buckets/{bucketId} | 删除桶(级联删文件) |
GET /storage/buckets/{bucketId}/files | 列出文件 |
POST /storage/buckets/{bucketId}/files | 上传文件(普通或分片首块) |
GET /storage/buckets/{bucketId}/files/{fileId} | 获取文件元数据 |
PUT /storage/buckets/{bucketId}/files/{fileId} | 更新文件名/权限 |
DELETE /storage/buckets/{bucketId}/files/{fileId} | 删除文件 |
GET /storage/buckets/{bucketId}/files/{fileId}/download | 下载(Content-Disposition: attachment) |
GET /storage/buckets/{bucketId}/files/{fileId}/preview | 图片预览(服务端图像变换) |
GET /storage/buckets/{bucketId}/files/{fileId}/view | 内联查看(浏览器直接打开) |
端点详解
大文件分片上传协议:当上传文件超过
5 MiB时,客户端需按5 MiB切块,首块fileId传unique()或自定义 ID,后续分块fileId传首块返回的$id,并在每次请求中附带Content-Range: bytes start-end/total与x-appwrite-id: <fileId>请求头。三种二进制读取端点差异:
/download附加Content-Disposition: attachment触发浏览器保存文件;/view附加Content-Disposition: inline供浏览器直接渲染 PDF/音视频/图片;/preview针对图片提供实时宽高缩放、圆角、边框、背景色与 WebP/AVIF 格式转换。
请求与响应
以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。上传类端点为 multipart/form-data,其余写端点为 application/json;认证头与示例变量约定见 通用约定。
GET /v1/storage/buckets
列出项目内全部桶。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
queries | query | string[] | 否 | 默认 [] | 可过滤字段:enabled、name、fileSecurity、maximumFileSize、encryption、antivirus、transformations |
search | query | string | 否 | 模糊搜索词(最长 256 字符),覆盖桶名 | |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 bucketList 模型:total + buckets[]。bucket 字段结构见 POST /v1/storage/buckets。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 匹配查询的桶总数 |
| buckets[] | bucket[] | 桶对象 |
调用示例:
curl \
"https://<your-endpoint>/v1/storage/buckets?queries[]=limit(25)&total=false" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"buckets": [
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}
]
}POST /v1/storage/buckets
创建桶并配置访问与处理策略。默认不授予任何用户角色——用户侧读文件需显式配置 permissions(见 permissions)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | body | string | 是 | 桶 ID:自定义或传 unique();可用字符 a-z、A-Z、0-9、.、-、_,最长 36 字符 | |
name | body | string | 是 | 桶名 | |
permissions | body | string[] | 否 | 桶级权限字符串数组,如 read("any");默认空数组(不授予任何用户角色) | |
fileSecurity | body | boolean | 否 | 默认 false | 开启文件级权限:用户持桶级或文件级任一权限即可访问文件 |
enabled | body | boolean | 否 | 默认 true | false 为访问开关:用户侧不可访问,API Key 仍可访问,文件不丢失 |
maximumFileSize | body | integer | 否 | 单文件上限(字节);超过返回 storage_invalid_file_size | |
allowedFileExtensions | body | string[] | 否 | 最多 100 个,每个最长 64 字符 | 扩展名白名单;空数组不限制 |
compression | body | string | 否 | none(默认)/ gzip / zstd | 压缩算法;超过 20MB 的文件即使开启也跳过压缩 |
encryption | body | boolean | 否 | 默认 true | 静态加密;超过 20MB 的文件跳过 |
antivirus | body | boolean | 否 | 默认 false | 病毒扫描;超过 20MB 的文件跳过 |
transformations | body | boolean | 否 | 默认 false | 是否开启图片变换(/preview 的前置条件) |
clientFileListing | body | boolean | 否 | 默认 true | 是否允许应用客户端列文件;false 时仅授权管理客户端可列文件,上传与单文件访问权限不变 |
输出:201,返回 bucket 模型。完整字段表:
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 桶 ID |
| $createdAt / $updatedAt | string | 创建/更新时间(ISO 8601) |
| $permissions | string[] | 桶级权限字符串(见 permissions) |
| fileSecurity | boolean | 是否启用文件级权限 |
| name | string | 桶名 |
| enabled | boolean | 是否启用;false 时用户侧不可访问,API Key 仍可访问 |
| maximumFileSize | integer | 单文件大小上限(字节) |
| allowedFileExtensions | string[] | 扩展名白名单(空数组表示不限制) |
| compression | string | 压缩算法:none / gzip / zstd |
| encryption | boolean | 是否静态加密 |
| antivirus | boolean | 是否病毒扫描 |
| transformations | boolean | 是否开启图片变换(preview 的前置条件) |
| totalSize | integer | 桶内文件总字节数 |
调用示例:
curl \
-X POST \
"https://<your-endpoint>/v1/storage/buckets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"bucketId": "app-assets",
"name": "App Assets",
"permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true
}'响应示例:
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}GET /v1/storage/buckets/{bucketId}
按 ID 获取桶配置。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID |
输出:200,返回 bucket 模型,字段见 POST /v1/storage/buckets。
调用示例:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 30000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}PUT /v1/storage/buckets/{bucketId}
更新桶配置。name 必填,其余参数可选;未传的配置项沿用当前值(permissions 传空数组表示清空)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
name | body | string | 是 | 桶名 | |
permissions | body | string[] | 否 | 桶级权限字符串数组;缺省沿用当前权限 | |
fileSecurity | body | boolean | 否 | 文件级权限开关 | |
enabled | body | boolean | 否 | 访问开关 | |
maximumFileSize | body | integer | 否 | 单文件上限(字节) | |
allowedFileExtensions | body | string[] | 否 | 扩展名白名单 | |
compression | body | string | 否 | none / gzip / zstd | 压缩算法 |
encryption | body | boolean | 否 | 静态加密开关 | |
antivirus | body | boolean | 否 | 病毒扫描开关 | |
transformations | body | boolean | 否 | 图片变换开关 | |
clientFileListing | body | boolean | 否 | 客户端列文件开关:false 时仅授权管理客户端可列文件;省略沿用当前值,上传与单文件访问权限不变 |
输出:200,返回 bucket 模型。
调用示例:
curl \
-X PUT \
"https://<your-endpoint>/v1/storage/buckets/app-assets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "App Assets",
"maximumFileSize": 50000000,
"transformations": true
}'响应示例:
{
"$id": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"fileSecurity": true,
"name": "App Assets",
"enabled": true,
"maximumFileSize": 50000000,
"allowedFileExtensions": [
"jpg",
"png",
"pdf"
],
"compression": "none",
"encryption": true,
"antivirus": false,
"transformations": true,
"totalSize": 17890
}DELETE /v1/storage/buckets/{bucketId}
删除桶并级联删除桶内全部文件,不可恢复。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID |
输出:204 No Content,无响应体。
调用示例:
curl \
-X DELETE \
"https://<your-endpoint>/v1/storage/buckets/app-assets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files
列出桶内文件。桶 clientFileListing=false 时,应用客户端(含匿名请求、用户 Session 与 JWT)不能列文件;已认证的服务端与项目管理请求仍受项目授权与 files.read scope 约束。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
queries | query | string[] | 否 | 默认 [] | 可过滤字段:name、signature、mimeType、sizeOriginal、chunksTotal、chunksUploaded |
search | query | string | 否 | 模糊搜索词(最长 256 字符),覆盖文件名 | |
total | query | boolean | 否 | 默认 true | 传 false 跳过计数 |
输出:200,返回 fileList 模型:total + files[]。file 字段结构见 POST /v1/storage/buckets/{bucketId}/files。
| 字段 | 类型 | 说明 |
|---|---|---|
| total | integer | 匹配查询的文件总数 |
| files[] | file[] | 文件对象 |
调用示例:
curl \
'https://<your-endpoint>/v1/storage/buckets/app-assets/files?queries[]=limit(25)&total=false' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"files": [
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "pink.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}
]
}POST /v1/storage/buckets/{bucketId}/files
上传文件(multipart/form-data,限流 60 次/分钟)。小文件单请求完成;大文件在同一端点走分片续传(见下方说明)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | body(form) | string | 是 | 文件 ID:自定义或传 unique();可用字符 a-z、A-Z、0-9、.、-、_,最长 36 字符 | |
file | body(form) | string(binary) | 是 | 二进制文件内容;SDK 提供 InputFile 封装,浏览器/Node 环境也可直接构造 | |
permissions | body(form) | string[] | 否 | 文件级权限字符串数组;需桶开启 fileSecurity 才生效,默认仅创建者(用户语境)持有全部权限 |
输出:201,返回 file 模型。完整字段表:
| 字段 | 类型 | 说明 |
|---|---|---|
| $id | string | 文件 ID |
| bucketId | string | 所属桶 ID |
| $createdAt / $updatedAt | string | 创建/更新时间(ISO 8601) |
| $permissions | string[] | 文件级权限字符串(桶开启 fileSecurity 时生效) |
| name | string | 文件名 |
| signature | string | 内容 MD5 签名(可用于校验完整性) |
| mimeType | string | 服务端识别的 MIME 类型 |
| sizeOriginal | integer | 原始大小(字节) |
| chunksTotal / chunksUploaded | integer | 总分片数与已上传分片数;二者相等即上传完成 |
| encryption | boolean | 是否静态加密 |
| compression | string | 实际使用的压缩算法:none / gzip / zstd |
调用示例:
curl \
-X POST \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F fileId="66a9d9ab03c7d" \
-F permissions[]='read("any")' \
-F file="@./pink.png"响应示例:
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "pink.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}分片上传(大文件续传):同一端点携带 X-Appwrite-ID: {fileId} 头与 Content-Range: bytes <start>-<end>/<total> 头、body 为分片二进制,反复调用直至 chunksUploaded == chunksTotal。中断后重复携带同一 fileId 即从断点续传,进度可经 GET .../files/{fileId} 的 chunksUploaded 查询。Content-Range 范围无效返回 storage_invalid_content_range / storage_invalid_range。分片调用示例:
curl -X POST "https://<your-endpoint>/v1/storage/buckets/app-assets/files" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Range: bytes 0-10485759/17890123" \
-H "X-Appwrite-ID: 66a9d9ab03c7d" \
--data-binary "@./pink.png.part0"GET /v1/storage/buckets/{bucketId}/files/{fileId}
获取文件元数据(不返回文件内容)。分片上传中可轮询 chunksUploaded 观察进度。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID |
输出:200,返回 file 模型,字段见 POST /v1/storage/buckets/{bucketId}/files。
调用示例:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "pink.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}PUT /v1/storage/buckets/{bucketId}/files/{fileId}
更新文件元数据(文件名与权限)。文件内容不可变——更新语义只覆盖元数据。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID | |
name | body | string | 否 | 新文件名 | |
permissions | body | string[] | 否 | 文件级权限字符串数组(全量替换);缺省沿用当前权限 |
输出:200,返回 file 模型。
调用示例:
curl \
-X PUT \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "pink-updated.png",
"permissions": [
"read(\"label:vip\")"
]
}'响应示例:
{
"$id": "66a9d9ab03c7d",
"bucketId": "app-assets",
"$createdAt": "2020-10-15T06:38:00.000+00:00",
"$updatedAt": "2020-10-15T06:38:00.000+00:00",
"$permissions": [
"read(\"label:vip\")"
],
"name": "pink-updated.png",
"signature": "5d529fd02b544198ae075bd57c1762bb",
"mimeType": "image/png",
"sizeOriginal": 17890,
"chunksTotal": 1,
"chunksUploaded": 1,
"encryption": true,
"compression": "none"
}DELETE /v1/storage/buckets/{bucketId}/files/{fileId}
删除单个文件(限流 60 次/分钟)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID |
输出:204 No Content,无响应体。
调用示例:
curl \
-X DELETE \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files/{fileId}/download
下载文件内容:响应携带 Content-Disposition: attachment 与 Content-Type: <文件 MIME>,浏览器触发保存。返回二进制流,非 JSON。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID | |
token | query | string | 否 | 文件令牌(见 file-tokens),用于无 Session/Cookie 场景(<img>、邮件链接) |
输出:200,返回文件二进制流;响应头含 Content-Type、Content-Length、Content-Disposition: attachment; filename="..."、ETag。
调用示例:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/download" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files/{fileId}/view
内联查看文件:Content-Disposition: inline,浏览器可直接打开(PDF/图片/文本)。返回二进制流,非 JSON。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID | |
token | query | string | 否 | 文件令牌(见 file-tokens) |
输出:200,返回文件二进制流(inline)。非图片文件仅原样返回,不做变换。
调用示例:
curl \
'https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/view?token=<TOKEN>' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/storage/buckets/{bucketId}/files/{fileId}/preview
图片预览:仅图片文件可用,服务端按查询参数实时变换图像。桶未开启 transformations 时返回 storage_bucket_transformations_disabled。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
bucketId | path | string | 是 | 桶 ID | |
fileId | path | string | 是 | 文件 ID(必须为图片) | |
width / height | query | integer | 否 | 默认 0(保持原比例),0–4000 | 目标宽/高(像素);只传其一则等比缩放 |
gravity | query | string | 否 | center(默认)/ top-left / top / top-right / left / right / bottom-left / bottom / bottom-right | 裁剪锚点 |
quality | query | integer | 否 | 默认 -1(沿用原图),0–100 | 输出质量 |
borderWidth | query | integer | 否 | 默认 0 | 边框宽度(像素) |
borderColor | query | string | 否 | 边框颜色(HEX,如 ff0000) | |
borderRadius | query | integer | 否 | 默认 0 | 圆角半径(像素) |
opacity | query | number | 否 | 默认 1,0–1 | 不透明度;仅对含透明通道的格式生效 |
rotation | query | integer | 否 | 默认 0,-360–360 | 旋转角度 |
background | query | string | 否 | 透明区域背景色(HEX,如 ffffff) | |
output | query | string | 否 | jpg / jpeg / png / webp / heic / avif / gif | 输出格式 |
token | query | string | 否 | 文件令牌(见 file-tokens) |
输出:200,返回变换后的图片二进制流(Content-Type 随 output 参数或原图格式)。
调用示例:
curl \
"https://<your-endpoint>/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/preview?width=400&height=300&gravity=center&quality=80&output=jpg" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"错误与边界
桶/文件不存在:
404+storage_bucket_not_found/storage_file_not_found;权限不匹配在下载/预览/查看路径同样返回storage_file_not_found(不泄露存在性)。重复 ID:
409+storage_bucket_already_exists/storage_file_already_exists。文件类型/大小违规:
storage_file_type_unsupported(扩展名白名单外)、storage_invalid_file_size(超maximumFileSize)、storage_invalid_file/storage_file_empty(空文件)。存储配额超限:
storage_limit_exceeded(413);项目对象存储限额只可从 quota/limits 类响应读取(见 projects)。压缩/加密/病毒扫描对超过 20MB 的文件自动跳过,不报错。
删除桶级联删除全部文件且不可恢复;
enabled=false只是访问开关。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Storage.listBuckets | GET /storage/buckets |
Storage.createBucket | POST /storage/buckets |
Storage.getBucket | GET /storage/buckets/{bucketId} |
Storage.updateBucket | PUT /storage/buckets/{bucketId} |
Storage.deleteBucket | DELETE /storage/buckets/{bucketId} |
Storage.listFiles | GET /storage/buckets/{bucketId}/files |
Storage.createFile | POST /storage/buckets/{bucketId}/files |
Storage.getFile | GET /storage/buckets/{bucketId}/files/{fileId} |
Storage.updateFile | PUT /storage/buckets/{bucketId}/files/{fileId} |
Storage.deleteFile | DELETE /storage/buckets/{bucketId}/files/{fileId} |
Storage.getFileDownload | GET .../files/{fileId}/download |
Storage.getFilePreview | GET .../files/{fileId}/preview |
Storage.getFileView | GET .../files/{fileId}/view |