Docs
文档目录

对象存储 API

桶(bucket)与文件(file)管理:桶的创建与策略配置、文件上传(含大文件分片续传)、元数据与权限维护、下载/预览/内联查看。文件短时访问令牌见 file-tokens,桶/文件双层权限语义见 permissions。

服务与资源边界

对象存储 API(/v1/storage/*)负责管理项目内的存储桶(Bucket,如展示项目中的知识库源文件桶 kb_enterprise_docs 与智能体多媒体桶 agent_multimedia_bucket)及文件(File)全生命周期:支持最大单文件大小限制、扩展名白名单、Gzip/Zstd 压缩、静态加密、ClamAV 病毒扫描、5MB 分片断点续传、在线图片裁剪/格式转换预览(/preview),并与知识库文档摄取和 Memory 多模态解析无缝衔接。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 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内联查看(浏览器直接打开)

端点详解

请求与响应

以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。上传类端点为 multipart/form-data,其余写端点为 application/json;认证头与示例变量约定见 通用约定。

GET /v1/storage/buckets

列出项目内全部桶。

输入:

参数位置类型必填默认/枚举说明
queriesquerystring[]否默认 []可过滤字段:enabled、name、fileSecurity、maximumFileSize、encryption、antivirus、transformations
searchquerystring否模糊搜索词(最长 256 字符),覆盖桶名
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 bucketList 模型:total + buckets[]。bucket 字段结构见 POST /v1/storage/buckets。

字段类型说明
totalinteger匹配查询的桶总数
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)。

输入:

参数位置类型必填默认/枚举说明
bucketIdbodystring是桶 ID:自定义或传 unique();可用字符 a-z、A-Z、0-9、.、-、_,最长 36 字符
namebodystring是桶名
permissionsbodystring[]否桶级权限字符串数组,如 read("any");默认空数组(不授予任何用户角色)
fileSecuritybodyboolean否默认 false开启文件级权限:用户持桶级或文件级任一权限即可访问文件
enabledbodyboolean否默认 truefalse 为访问开关:用户侧不可访问,API Key 仍可访问,文件不丢失
maximumFileSizebodyinteger否单文件上限(字节);超过返回 storage_invalid_file_size
allowedFileExtensionsbodystring[]否最多 100 个,每个最长 64 字符扩展名白名单;空数组不限制
compressionbodystring否none(默认)/ gzip / zstd压缩算法;超过 20MB 的文件即使开启也跳过压缩
encryptionbodyboolean否默认 true静态加密;超过 20MB 的文件跳过
antivirusbodyboolean否默认 false病毒扫描;超过 20MB 的文件跳过
transformationsbodyboolean否默认 false是否开启图片变换(/preview 的前置条件)
clientFileListingbodyboolean否默认 true是否允许应用客户端列文件;false 时仅授权管理客户端可列文件,上传与单文件访问权限不变

输出:201,返回 bucket 模型。完整字段表:

字段类型说明
$idstring桶 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
$permissionsstring[]桶级权限字符串(见 permissions)
fileSecurityboolean是否启用文件级权限
namestring桶名
enabledboolean是否启用;false 时用户侧不可访问,API Key 仍可访问
maximumFileSizeinteger单文件大小上限(字节)
allowedFileExtensionsstring[]扩展名白名单(空数组表示不限制)
compressionstring压缩算法:none / gzip / zstd
encryptionboolean是否静态加密
antivirusboolean是否病毒扫描
transformationsboolean是否开启图片变换(preview 的前置条件)
totalSizeinteger桶内文件总字节数

调用示例:

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 获取桶配置。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 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 传空数组表示清空)。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
namebodystring是桶名
permissionsbodystring[]否桶级权限字符串数组;缺省沿用当前权限
fileSecuritybodyboolean否文件级权限开关
enabledbodyboolean否访问开关
maximumFileSizebodyinteger否单文件上限(字节)
allowedFileExtensionsbodystring[]否扩展名白名单
compressionbodystring否none / gzip / zstd压缩算法
encryptionbodyboolean否静态加密开关
antivirusbodyboolean否病毒扫描开关
transformationsbodyboolean否图片变换开关
clientFileListingbodyboolean否客户端列文件开关: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}

删除桶并级联删除桶内全部文件,不可恢复。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 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 约束。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
queriesquerystring[]否默认 []可过滤字段:name、signature、mimeType、sizeOriginal、chunksTotal、chunksUploaded
searchquerystring否模糊搜索词(最长 256 字符),覆盖文件名
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 fileList 模型:total + files[]。file 字段结构见 POST /v1/storage/buckets/{bucketId}/files。

字段类型说明
totalinteger匹配查询的文件总数
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 次/分钟)。小文件单请求完成;大文件在同一端点走分片续传(见下方说明)。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdbody(form)string是文件 ID:自定义或传 unique();可用字符 a-z、A-Z、0-9、.、-、_,最长 36 字符
filebody(form)string(binary)是二进制文件内容;SDK 提供 InputFile 封装,浏览器/Node 环境也可直接构造
permissionsbody(form)string[]否文件级权限字符串数组;需桶开启 fileSecurity 才生效,默认仅创建者(用户语境)持有全部权限

输出:201,返回 file 模型。完整字段表:

字段类型说明
$idstring文件 ID
bucketIdstring所属桶 ID
$createdAt / $updatedAtstring创建/更新时间(ISO 8601)
$permissionsstring[]文件级权限字符串(桶开启 fileSecurity 时生效)
namestring文件名
signaturestring内容 MD5 签名(可用于校验完整性)
mimeTypestring服务端识别的 MIME 类型
sizeOriginalinteger原始大小(字节)
chunksTotal / chunksUploadedinteger总分片数与已上传分片数;二者相等即上传完成
encryptionboolean是否静态加密
compressionstring实际使用的压缩算法: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 观察进度。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 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}

更新文件元数据(文件名与权限)。文件内容不可变——更新语义只覆盖元数据。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 ID
namebodystring否新文件名
permissionsbodystring[]否文件级权限字符串数组(全量替换);缺省沿用当前权限

输出: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 次/分钟)。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 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。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 ID
tokenquerystring否文件令牌(见 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。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 ID
tokenquerystring否文件令牌(见 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。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 ID(必须为图片)
width / heightqueryinteger否默认 0(保持原比例),0–4000目标宽/高(像素);只传其一则等比缩放
gravityquerystring否center(默认)/ top-left / top / top-right / left / right / bottom-left / bottom / bottom-right裁剪锚点
qualityqueryinteger否默认 -1(沿用原图),0–100输出质量
borderWidthqueryinteger否默认 0边框宽度(像素)
borderColorquerystring否边框颜色(HEX,如 ff0000)
borderRadiusqueryinteger否默认 0圆角半径(像素)
opacityquerynumber否默认 1,0–1不透明度;仅对含透明通道的格式生效
rotationqueryinteger否默认 0,-360–360旋转角度
backgroundquerystring否透明区域背景色(HEX,如 ffffff)
outputquerystring否jpg / jpeg / png / webp / heic / avif / gif输出格式
tokenquerystring否文件令牌(见 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>"

错误与边界

与 Server SDK 的对应

service.method端点
Storage.listBucketsGET /storage/buckets
Storage.createBucketPOST /storage/buckets
Storage.getBucketGET /storage/buckets/{bucketId}
Storage.updateBucketPUT /storage/buckets/{bucketId}
Storage.deleteBucketDELETE /storage/buckets/{bucketId}
Storage.listFilesGET /storage/buckets/{bucketId}/files
Storage.createFilePOST /storage/buckets/{bucketId}/files
Storage.getFileGET /storage/buckets/{bucketId}/files/{fileId}
Storage.updateFilePUT /storage/buckets/{bucketId}/files/{fileId}
Storage.deleteFileDELETE /storage/buckets/{bucketId}/files/{fileId}
Storage.getFileDownloadGET .../files/{fileId}/download
Storage.getFilePreviewGET .../files/{fileId}/preview
Storage.getFileViewGET .../files/{fileId}/view